Send Flow Template Messages
With the ‘Flow Template API’ message, you can collect business-related information from customers and their purchase interests in a simpler and faster way without an agent's intervention. You can build a WhatsApp 'flow' and send it as a template message. To send a flow template message, you must first create a flow template.
For more information on the WhatsApp Flow and WhatsApp Template Messages, see the following documents:
General introduction and overview about flow messages
How to create a flow message using WhatsApp Template
How to create a flow message using WhatsApp Interactive message.
In the messaging_object of the payload, specify the flow details.
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.io, 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.
Base URL
https://<api_domain>/v2/<SID>
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.ap.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
API Request to Send Flow Template Message
To send a 'flow template' message, use the https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages
endpoint with the following request method.
curl -X POST \
https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages \
-H 'Content-Type: application/json' \
-H 'api-key: <api-key>' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "<messaging_product>",
"recipient_type": "<recipient_type>",
"to": "<to_number>",
"type": "<type>",
"template": {
"name": "<template_name>",
"language": {
"code": "<language_locale_code>"
},
"components": [
{
"type": "<componet_type>",
"sub_type": "<component_sub_type>",
"index": <value>,
"parameters": [
{
"type": "<type>",
"action": {
"flow_token": "<flow_token>",
"flow_action_data": {}
}
}
]
}
]
}
},
"extra_info": {
"ref": "<ref>",
"ref1": "<ref2>",
"ref2": "<ref2>",
"wa_source": "<wa_source>"
}
}'
Sample Request Format
curl -X POST \
https://api.in.kaleyra.io/v2/HAXP2142XX/whatsapp/+91863XXX5920/messages \
-H 'Content-Type: application/json' \
-H 'api-key: AVGSCFSAFS53215634XXXXX4ac' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+91xxxxxxxxxx",
"type": "template",
"template": {
"name": "flow_template20",
"language": {
"code": "en_US"
},
"components": [
{
"type": "button",
"sub_type": "flow",
"index": 0,
"parameters": [
{
"type": "action",
"action": {
"flow_token": "flow_token",
"flow_action_data": {}
}
}
]
}
]
}
},
"extra_info": {
"ref": "customer1",
"ref1": "marketing",
"ref2": "dictionary",
"wa_source": "api"
}
}'
URL Parameters and Headers
Following is the list of parameters and headers to send the outgoing message request:
Parameter / Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | HXAP16XXXXXX97IN | Yes |
phone_number | String | Phone number of the end customer you want to send a message to. | +91XXXXXXXXXX | Yes (valid phone numbers only) |
Content-Type | String | Indicates the format of the content the API will be processing. | The only allowed value is application/json. | Yes |
api-key | String | API key generated from kaleyra platform account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
Following is the list of attributes to be used in the payload to send the outgoing message:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_object | JSON object | Payload is supported only in JSON format. The messaging_object is the payload which contains the message object as defined by Meta which is used to send the WhatsApp message. | See the specific table for details. | Yes |
extra_info | JSON object | This object will contain additional details that a user can send for certain functionalities. | See the specific table for details. | No |
The following table describes the different attributes used for the messaging_object
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_product | String | Messaging service used for the request. | The only allowed value is 'whatsapp'The only. | Yes |
recipient_type | String | Currently, you can only send messages to individuals. Default is individual. | The only allowed value is 'individual'. | No |
to | String | WhatsApp end-user phone number. It should include country code prefix following E.164 format. | +91XXXXXXXXXX | Yes |
type | String | The type of message you want to send. If omitted, defaults to text. | The only allowed value for sending this message is 'template'. | No |
template | JSON Object | Details of the flow template object | See the specific table for details. | Yes |
The following table describes the different attributes used for the template JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
name | String | Name of the template used. | flow_template20 | Yes |
language | JSON Object | The language used in the template. | See the specific table for details. | Yes |
components | JSON Object | The components used in the flow template. | See the specific table for details. | Yes |
The following table describes the different attributes used for the 'language' JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
language | String | The language used in the template. | en_US | Yes |
The following table describes the different attributes used in components.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | The type of component. | button | Yes |
sub_type | String | The sub type of the component. | flow | Yes |
index | Numeric | The order of the component on the display screen. | 0 | Yes |
parameters | JSON Object | The parameters of the button component. | See the specific table for details. | Yes |
The following table describes the different attributes of the 'parameters' object.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
type | String | The parameter type. | action | Yes |
action | JSON Object | The action that should be done when the button is tapped. | See the specific table for details. | Yes |
The following table describes the different attributes of the 'action' object.
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
flow_token | String | The flow token that is used for the message. Note: Flow token is generated by the business to serve as an identifier. | xxxxxAACS5FpgQ_cAAAAAD0xxxx | No |
flow_action_data | Array | The first action that should start when the flow starts. It can be either a ‘data request’ or ‘navigate’. The default value is ‘navigate’. | navigate | No |
The following table describes the different attributes used for the extra_info
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
ref | String | Include any contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | customer1 | No |
ref1 | String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | marketing | No |
ref2 | String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | dictionary | No |
wa_source | String | Indicates the source from where the API has been triggered. Supported values for wa_source are "api", "clevertap", "zoho", "webengage", "shopify", "leadsquared", "responsys", "braze", "hubspot", "salesforce", "zapier", "eloqua", and "moengage". Note: If the customer passes any other value other than above-specified values, then the system will override that as the "API". | api | No |
Sample Success Response
The following success message appears with the status 202 Accepted:
202 Accepted
{
"code":"WA202"
"message":"Request Accepted",
"data":{
"message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}
Following are the error responses for the API level and the business level validations.
Sample Failure Response
The following are the failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
401 Unauthorized phone number
{
"code": "WA401",
"message": "Phone number is not present or does not belong to the account.",
"data": {},
"error": {
"phone_number": "Phone number is not present or does not belong to the account."
}
}
400 Incorrect payload
{
"code": "WA400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
500 Internal Server Error
{
"code": "WA500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
400 Low balance
{
"code": "E110",
"message": "Please check your balance, You have a low balance!",
"data": {},
"error": {
"balance": "Please check your balance, You have a low balance!"
}
}
401 Unauthorised Account type
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": {
"account": "API is not available for given customer.Please contact support for more info"
}
}
401 Unauthorized phone number version
{
"code": "WA-401",
"message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
Updated about 12 hours ago