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

https://api.kaleyra.io/v1/

Request Format

curl --location --request POST '{{gocloud}}/v1/{{sid}}/failover' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "config_id": ,
    "recipient": [{
        "to": ,
        "email":
    }],
    "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 '{{gocloud}}/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]"
    }],
    "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.

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

CALLBAK_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 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

WHATSAPP

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

BODY

String

The body of the message. Emojis and markdown are supported.

Maximum length: 1024 characters.

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.

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."Avi", "Kaleyra", "Mr Avinash"No
CAMPAIGN_NAMEStringName of the campaign.26th Jul21 - 10:48 AM CampaignNo

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",
    "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 Avinash"
            ]
        },
        "soip": {
            "params": [
                "Avi",
                "Kaleyra",
                "Mr Avinash"
            ]
        },
    }
}

Did this page help you?