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.

📘
Note:
the /failover endpoint is available only for customers in the Indian Pod

👍
Base URL
https://api.kaleyra.io/v1/

Request Format

curl --location --request POST '{{URL}}/v1/{{SID}}/failover' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: {{content_type}}' \
--data-raw '{
	"config_id": "{{config_id}}",
	"recipient": [{
		"to": "{{to_number}}",
		"email": "{{email_id}}",
	}],
 "ref": "{{ref}}",
 "ref1": "{{ref1}}",
 "ref2": "{{ref2}}"
	"replacables": {
		"global": "{{global}}",
		"whatsapp": {
			"params": "{{params}}",
			"media_url": "{{media_url}}",
			"param_header": "{{param_header}}",
			"ip":{{ip}}',
			"param_url": "{{parm_url}}",
			"caption": "{{caption}}",
			"lang_code": "{{lang_code}}",
			"preview_url": "{{preview_url}}",
			"param_lat": "{{param_lat}}",
			"param_long": "{{param_long}}",
			"param_address": "{{param_address}}",
			"param_name": "{{param_name}}",
			"language": "{{language}}",
			"type": "{{type}}",
			"header": "{{header}}",
			"footer": "{{footer}}" 
		},
		"sms": {
			"body": "{{body}}",
			"params": "{{params}}" 
		},
		"soip": {
			"params": "{{params}}",
			"campaign_name": "{{capmaign_name}}" 
		},
	}
}'

Parameters and Data Types

Following is the list of parameters and data types supported:

Parameters	Data Type	Description	Example	Mandatory
SID	String	Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.	HXXXXXXX071US	Yes
API_KEY	String	The API Key that you have generated in the Kaleyra.io.	Ac4XXXXX21f	Yes
CONTENT_TYPE	String	The format in which the data is sent.	application/x-www-form-urlencoded	Yes
CONFIG_ID	String	Failover configuration ID to be obtained from the UI. For more information refer to Failover Configuration.	6fddacfb-2e76-4d3d-8b2a-46ae6a7xxxc5	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 value 1.	abc	No
REF1	String	Optional. Custom value 2.	123	No
REF2	String	Optional. Custom value 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. For more information related to callback profiles, see callback profiles page. 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 a callback sent to the 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>" } For more information related to parameter fields and description, see Parameters and Data Types table.	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": ["Jhn", "Kaleyra", "Mr John"]}	No
WHATSAPP	Object	An object containing an array of parameters and other details to be used for WhatsApp.	{ "params": ["Jhn", "Kaleyra", "Mr John"], "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.8464xx, "param_long": -94.5474xx, "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": ["Jhn", "Kaleyra", "Mr John"] }	No
SOIP	Object	An array of parameters and campaign key.	{ "params": ["Jhn", "Kaleyra", "Mr John"], "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.	"Jhn", "Kaleyra", "Mr John"	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	Latitude 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.	"Jhn", "Kaleyra", "Mr John"	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.	"Jhn", "Kaleyra", "Mr John"	No
CAMPAIGN_NAME	String	Name of the campaign.	26th Jul21 - 10:48 AM Campaign	No

Sample Request

curl --location --request POST '{{URL}}/v1/HXXXXXXX071US/failover' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "config_id": "de86fe5d-02ab-455a-9893-ce6e2afxxxxf",
    "recipient": [{
        "to": "9199XXXXXX40",
        "email": "[email protected]"
    }],
    "ref":"abc",
    "ref1":"123",
    "ref2":"123",
    "replacables": { 
        "global": null,
        "whatsapp": {
            "params": ["Jhn", "Kaleyra", "Mr John"],
            "media_url": "https://s3.ap-south-1.amazonaws.com/stage-hexa/docs/165665xxx7Screenshot_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.846xxx,
            "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": ["Jhn", "Kaleyra", "Mr John"]
        },
        "soip": {
            "params": ["Jhn", "Kaleyra", "Mr John"],
            "campaign_name": "26th Jul21 - 10:48 AM Campaign"
        },
    }
}'

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": [
                "Jhn",
                "Kaleyra",
                "Mr John"
            ],
            "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": [
                "Jhn",
                "Kaleyra",
                "Mr Test"
            ]
        },
        "soip": {
            "params": [
                "Jhn",
                "Kaleyra",
                "Mr John"
            ]
        },
    }
}

Error Codes

For information related to the Failover error code, see Failover Error Codes page.

Updated 6 months ago