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:

ParametersData TypeDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USYes
API_KEYStringThe API Key that you have generated in the Kaleyra.io.Ac4XXXXX21fYes
CONTENT_TYPEStringThe format in which the data is sent.application/x-www-form-urlencodedYes
CONFIG_IDStringFailover configuration ID to be obtained from the UI. For more information refer to Failover Configuration.6fddacfb-2e76-4d3d-8b2a-46ae6a7xxxc5Yes
RECIPIENTArray of objectsEach 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.
REFStringOptional. Custom value 1. abcNo
REF1StringOptional. Custom value 2.123No
REF2StringOptional. Custom value 3.123No
REPLACEABLESArray of objectsValues 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_IDStringA 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-6ed654272XXXNo

Following is the list of parameters and data types of the REPLACEABLES object:

ParameterData TypeDescriptionExampleMandatory
GLOBALObjectAn array of params to be used globally. Used in case individual params are not obtained.{"params": ["Jhn", "Kaleyra", "Mr John"]}No
WHATSAPPObjectAn 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
SMSObjectAn array of parameters and body key.{
"body": "Testing body content",
"params": ["Jhn", "Kaleyra", "Mr John"]
}
No
SOIPObjectAn 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.

ParameterData TypeDescriptionExampleMandatory
PARAMSStringThe 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_URLStringMedia URL if anyhttps://www.kaleyra.com/wp-content/uploads/kaleyra.png No
PARAM_HEADERStringTitle/Subject of the headerTestingNo
IPStringIP address18.XXX.XXX.194No
PARAM_URLStringThe values that are set dynamically in a page's URL, and can be accessed by its template and its data sources.LoginNo
CAPTIONStringA caption for the message.Sample mediaNo
LANG_CODEStringThe 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.
enNo
PREVIEW_URLStringThe URL you want to include in the message.https://www.facebook.com/KaleyraPlatformNo
PARAM_LATStringLatitude value for location message.38.846439No
PARAM_LONGStringLongitude value for location message.-94.547432No
PARAM_ADDRESSStringSpecifies the registered WhatsApp number address.567, "Test", 2nd Phase, Bangalore.No
PARAM_NAMEStringInputs for contact message (first_name, formatted_name)HomeNo
LANGUAGEStringIndicates the language code value for the WhatsApp template language.enNo
TYPEStringType of the messageLocation, contact, text, and so on.No
HEADERStringIf 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 messageNo
FOOTERStringThe footer of the message. Emojis and markdown are supported. The maximum length is set to 60 characters.contact customer support for further detailsNo

Following is the list of parameters and data types of the SMS object in REPLACEABLES.

ParameterData TypeDescriptionExampleMandatory
BODYStringThe body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.
Hi, Your order has been shipped.No
PARAMSStringThe 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.

ParameterData TypeDescriptionExampleMandatory
PARAMSStringThe 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_NAMEStringName of the campaign.26th Jul21 - 10:48 AM CampaignNo

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.