Failover Messages
Use this API to trigger the Failover configuration and deliver the message to your users.
The Failover Messages API lets you trigger the failover configuration using the /failover endpoint.
Base URL
Request Format
curl --location --request POST '{{URL}}/v1/{{SID}}/failover' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"config_id": ,
"recipient": [{
"to": ,
"email":
}],
"ref":"",
"ref1":"",
"ref2":"",
"replacables": {
"global":
"whatsapp": {
"params": ,
"media_url": "",
"param_header": ,
"ip": ,
"param_url": null,
"caption": ,
"callback_url": "",
"lang_code": "",
"preview_url": ,
"param_lat": ,
"param_long": ,
"param_address": ,
"param_name": null,
"language": ,
"type": ,
"header": ,
"footer":
},
"sms": {
"body": "",
"params":""
},
"soip": {
"params": ,
"campaign_name": ""
},
}
}'
Sample Request
curl --location --request POST '{{URL}}/v1/{{SID}}/failover' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"config_id": "de86fe5d-02ab-455a-9893-ce6e2af366ff",
"recipient": [{
"to": "9199XXXXXX40",
"email": "[email protected]"
}],
"ref":"abc",
"ref1":"123",
"ref2":"123",
"replacables": {
"global": null,
"whatsapp": {
"params": ["Avi", "Kaleyra", "Mr Avinash"],
"media_url": "https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/1656659317Screenshot_from_2022-07-01_10-54-58.png",
"param_header": "abcd",
"ip": "1XX.X.X.1",
"param_url": "login",
"caption":"test image",
"lang_code": "",
"preview_url": true,
"param_lat": 38.846439,
"param_long": -94.547432,
"param_address": "The Pavilion, 1st Floor #175 & 176, Bannerghatta Main Rd, JP Nagar 4th Phase, Bilekahalli, Bengaluru, Karnataka 560076",
"param_name": "Home",
"language": "en",
"type": "location",
"header": "promotional message",
"footer": "contact customer support for further details"
},
"sms": {
"body": "Testing body content",
"params": ["Avi", "Kaleyra", "Mr Avinash"]
},
"soip": {
"params": ["Avi", "Kaleyra", "Mr Avinash"],
"campaign_name": "26th Jul21 - 10:48 AM Campaign"
},
}
}'
Parameters and Data Types
Following is the list of parameters and data types supported:
Parameters | Data Type | Description | Example | Mandatory |
---|---|---|---|---|
CONFIG_ID | String | Failover configuration ID to be obtained from the UI. For more information refer to Failover Configuration. | 6fddacfb-2e76-4d3d-8b2a-46ae6a75ccc5 | Yes |
RECIPIENT | Array of objects | Each object will have a number and an email ID. | [{ "to": "91XXXXXXXX40", "email":“[email protected]“}] | Depending on the Failover configuration, both email and phone number may not mandatory. For example, if the failover is SMS, RCS and SoIP, then the email won't be required. |
REF | String | Optional custom variable 1. | abc | No |
REF1 | String | Optional custom variable 2. | 123 | No |
REF2 | String | Optional custom variable 3. | 123 | No |
REPLACEABLES | Array of objects | Values for various channels parameter string. Replaces the variables sequentially in the template body. | Parameters > ["Jane", "[email protected]", "John"] Body > Hi {name}, your email, {email}, is successfully updated. Thanks, {name} Replaced Body > Hi Jane, your email, [email protected], is successfully updated. Thanks, John | No |
CALLBACK_PROFILE_ID | String | A unique callback profile ID set for each account for a callback. The callback given to the client is specific to failover and not specific to channels. It will have details regarding what happened to the channel in the config. Sample of callback sent to client: { "ref": "", "ref1": "", "ref2": "", "kid": "", "config_id": "<config_id>", "delivered": "", "channel_status_id": "<channel_status_id>", "failover_id": "<failover_id>", "channel": "", "mobile": "", "email": "", "channel_priority": "<channel_priority>", "status_trace": "<status_trace>" } | IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX | No |
Following is the list of parameters and data types of the REPLACEABLES object:
Parameter | Data Type | Description | Example | Mandatory |
---|---|---|---|---|
GLOBAL | Object | An array of params to be used globally. Used in case individual params are not obtained. | {"params": ["Avi", "Kaleyra", "Mr Avinash"]} | No |
Object | An object containing an array of parameters and other details to be used for WhatsApp. | { "params": ["Avi", "Kaleyra", "Mr Avinash"], "media_url": "https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/1656659317Screenshot_from_2022-07-01_10-54-58.png ", "param_header": "abcd", "ip": "127.0.0.1", "param_url": "login", "caption": null, "lang_code": "en", "preview_url": true, "param_lat": 38.846439, "param_long": -94.547432, "param_address": "The Pavilion, 1st Floor #175 & 176, Bannerghatta Main Rd, JP Nagar 4th Phase, Bilekahalli, Bengaluru, Karnataka 560076", "param_name": "Home", "language": "en", "type": "location", "header": "header", "footer": "footer" } | No | |
SMS | Object | An array of parameters and body key. | { "body": "Testing body content", "params": ["Avi", "Kaleyra", "Mr Avinash"] } | No |
SOIP | Object | An array of parameters and campaign key. | { "params": ["Avi", "Kaleyra", "Mr Avinash"], "campaign_name": "26th Jul21 - 10:48 AM Campaign" } | No |
Following is the list of parameters and data types of the WHATSAPP object in REPLACEABLES.
Parameter | Data Type | Description | Example | Mandatory |
---|---|---|---|---|
PARAMS | String | The values that you will pass when you want to send a message using the template. Since the values are dynamic, they must be passed through the key. Multiple parameters are allowed that must be separated with a comma. | "Avi", "Kaleyra", "Mr Avinash" | No |
MEDIA_URL | String | Media URL if any | https://www.kaleyra.com/wp-content/uploads/kaleyra.png | No |
PARAM_HEADER | String | Title/Subject of the header | Testing | No |
IP | String | IP address | 18.XXX.XXX.194 | No |
PARAM_URL | String | The values that are set dynamically in a page's URL, and can be accessed by its template and its data sources. | Login | No |
CAPTION | String | A caption for the message. | Sample media | No |
LANG_CODE | String | The language code of the language that the template will allow. 'en' is the code for English. For a comprehensive list of supported languages, read this. | en | No |
PREVIEW_URL | String | The URL you want to include in the message. | https://www.facebook.com/KaleyraPlatform | No |
PARAM_LAT | String | Lattitude value for location message. | 38.846439 | No |
PARAM_LONG | String | Longitude value for location message. | -94.547432 | No |
PARAM_ADDRESS | String | Specifies the registered WhatsApp number address. | 567, "Test", 2nd Phase, Bangalore. | No |
PARAM_NAME | String | Inputs for contact message (first_name, formatted_name) | Home | No |
LANGUAGE | String | Indicates the language code value for the WhatsApp template language. | en | No |
TYPE | String | Type of the message | Location, contact, text, and so on. | No |
HEADER | String | If you decide to include the header text, you must set the header’s type to text and add a text field with the desired content. | promotional message | No |
FOOTER | String | The footer of the message. Emojis and markdown are supported. The maximum length is set to 60 characters. | contact customer support for further details | No |
Following is the list of parameters and data types of the SMS object in REPLACEABLES.
Parameter | Data Type | Description | Example | Mandatory |
---|---|---|---|---|
BODY | String | The body of the message. Emojis and markdown are supported. Maximum length: 1024 characters. | Hi, Your order has been shipped. | No |
PARAMS | String | The values that you will pass when you want to send a message using the template. Since the values are dynamic, they must be passed through the key. Multiple parameters are allowed that must be separated with a comma. | "Avi", "Kaleyra", "Mr Avinash" | No |
Following is the list of parameters and data types of the SOIP object in REPLACEABLES.
Parameter | Data Type | Description | Example | Mandatory |
---|---|---|---|---|
PARAMS | String | The values that you will pass when you want to send a message using the template. Since the values are dynamic, they must be passed through the key. Multiple parameters are allowed that must be separated with a comma. | "Avi", "Kaleyra", "Mr Avinash" | No |
CAMPAIGN_NAME | String | Name of the campaign. | 26th Jul21 - 10:48 AM Campaign | No |
Response Format
{
"config_id": "de86fe5d-02ab-455a-9893-ce6e2af366ff",
"recipients": [
{
"email": "[email protected]",
"failover_id": "80205113-66d3-42cd-98b4-b955b144fbc6:0",
"to": "919XXXXXXXX0"
}
],
"kid": "80205113-66d3-42cd-98b4-b955b144fbc6",
"created_at": "2022-07-04 05:49:11+00:00",
"ref":"abc",
"ref1":"123",
"ref2":"123",
"replacables": {
"whatsapp": {
"params": [
"Avi",
"Kaleyra",
"Mr Avinash"
],
"media_url": "https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/1656659317Screenshot_from_2022-07-01_10-54-58.png",
"param_header": "abcd",
"param_url": "login",
"preview_url": true,
"param_lat": 38.846439,
"param_long": -94.547432,
"param_name": "Home",
"language": "en",
"type": "location",
"header": "header",
"footer": "footer"
},
"sms": {
"body": "Testing body content",
"params": [
"Avi",
"Kaleyra",
"Mr Test"
]
},
"soip": {
"params": [
"Avi",
"Kaleyra",
"Mr Test"
]
},
}
}
Updated about 12 hours ago