Migrate Flow

POST Method

Kaleyra platform's Migrate Flow API enables you to migrate a given flow from one WhatsApp Business Account (WABA) ID to another. Migration doesn't move the source Flows, it creates copies of them with the same names in the destination WABA.

📘
Notes:

Ensure to indicate the correct destination WABA ID before migrating a flow.

You can specify specific Flow names to migrate or choose to migrate all Flows in the source WABA.

Flows can only be migrated between WABAs owned by the same Meta business.

If a Flow exists with the same name in the destination WABA, it will be skipped, and the API will return an error message for that Flow. Other Flows in the same request will be copied.

The migrated Flow will be published if the original Flow is published; otherwise, it will be in draft state.

New Flows under destination WABA will have new Flow IDs.

More than one flow can be migrated at a time.

Prerequisites

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on Kaleyra platform.
To set up a WhatsApp account on Kaleyra platform, see Manual Signup
and Embedded Signup.
An active WhatsApp for Business API plan that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
- A WABA ID onboarded on Kaleyra WhatsApp API V2.

Base URL

https://<api_domain>/v2/<SID>

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

API request to migrate a flow

To migrate a flow from one WABA ID to another, use the following endpoint with the request method: https://<api_domain>/v2/<sid>/whatsapp/<source_waba_id>/migrate_flows/<destination_waba_id>.

Request Format

The following is the request format to migrate a flow:

curl --location --request POST 'http://<api_domain>/v2/<sid>/whatsapp/<source_waba_id>/migrate_flows/<destination_waba_id>' \
--header 'api-key: <api-key>' \
--header 'Content-Type: <Content-Type>' \
--data '{
  "flow_names": [<flow_names>]
}'

Sample Request Format

The following is the sample request format to migrate a flow:

curl --location --request POST 'https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/112xxxxxxxxxx207/migrate_flows/116xxxxxxxxxx342'\
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data '{
  "flow_names": [My first flow]
}'

URL Parameters and Headers

Following is the list of parameters and headers to migrate a flow:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXAP16XXXXXX97IN	Yes
`source_waba_id`	String	The source WABA ID from which you want to migrate the flow.	112xxxxxxxxxx207	Yes
`destination_waba_id`	String	The destination WABA ID to which you want to migrate the flow.	116xxxxxxxxxx342	Yes
`api-key`	String	API key generated from Kaleyra account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`flow_names`	Array of string	Flow name that you want to migrate. List of specific Flow names to migrate. If not specified, it will migrate all flows in the source WABA. Only 100 Flows can be migrated in a request.	My first flow	No

Sample Success Response

The following success message appears with the status 200 Accepted:

200 OK
{
    "migrated_flows": [
        {
            "source_id": "112xxxxxxxxxx207",
            "source_name": "My first flow",
            "migrated_id": "116xxxxxxxxxx342"
        }
    ],
    "failed_flows": []
}

Sample response if 1 flow is migrated and another fails.

200 OK  

{ 
  "migrated_flows": [ 
    { 
      "source_name": "appointment-booking", 
      "source_id": "111 xxxxxxxxxx999", 
      "migrated_id": "567xxxxxxxxxx888" 
    } 
  ], 
  "failed_flows": [ 
    { 
      "source_name": "lead-gen", 
      "error_code": "423xxxxxxxxxx777 ", 
      "error_message": "Flows Migration Error: Flow with the same name exists in destination WABA." 
    } 
  ] 
}

Sample Failure Response

The following are the failure responses:

WABA version check. WABA should be onboarded with the latest version of Kaleyra API (V2 version).

401 Unauthorized WABA
{
    "code": "WA401",
    "message": "Waba_Id is not present or does not belong to the account.",
    "data": {},
    "error": {
        "waba_id": "Waba_Id is not present or does not belong to the account."
    }
}

API Key and SID validations.

401 Unauthorized
{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "error": "Incorrect SID or API key."
    }

Payload Validations if all the required fields are passed in the payload.

400 Incorrect payload
{
    "code": "WA400",
    "message": "Refer to correct payload format",
    "data": {},
    "error": {
        "payload": "Incorrect payload format"
    }

Internal Server Errors.

{
    "code": "WA500",
    "message": "Please try again later",
    "data": {},
    "error": {
        "error": "Internal server error"
    }
}

Meta Errors are passed the same as original error messages.

Status Code as given by Meta
{
    "error": {
        "message": "An unknown error has occurred.",
        "type": "OAuthException",
        "code": 1,
        "fbtrace_id": "AbOz4LZefxFSWTkhGPZnTBw"
    }
}

Rate limit check to restrict up to 20 requests per Hour per WABA for Create Flow API.

429 Too many requests
{
    "code": "WA429",
    "message": "Rate limit hit",
    "data": {},
    "error": {
        "error": "Too many requests sent from this waba in a short period of time, please try after sometime"
    }
}

Flow ID Check: for all endpoints having flow_id, the ID will be validated to check if the flow_id exists in the provided source WABA.

404 Flow Id not found
{
    "code": "WA404",
    "message": "flow_id is not present or does not belong to the account.",
    "data": {},
    "error": {
        "flow_id": "flow_id is not present or does not belong to the account."
    }
}

Updated 9 days ago