Invocation API
POST Method
The Fallback Invocation API allows you to trigger any specified Fallback Flow.
Note:
To initiate Flow, you must provide any needed dynamic data that has not been configured through the Fallback wizard.
Base URL
https://<api_domain>/v1/<SID>
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
NA pod | api.na.kaleyra.ai |
API request for Fallback Workflow Invocation
To trigger a Fallback Workflow Invocation, use the POST request method with the https://<api_domain>/v1/<sid>/workflow/v1/instances/workflow_instance_id/invoke
endpoint.
Request Format - Fallback Workflow Invocation
The Fallback configuration needs to be set up using the Fallback wizard. For more information on the Fallback documentation, see Fallback Dashboard. As a result, you are only required to specify the missing dynamic parameters, such as the recipient and template parameters, for each channel within the Send object in the request body. In this case, 'send1' represents the first channel configured in the user interface, while 'send2' refers to the second channel. No additional Fallback configuration parameters are required, as the channel, template, timeout, and media URL (for WhatsApp templates only) have all been pre-configured through the User Interface.
curl -X POST --location https://<api_domain>/v1/<sid>/workflow/v1/instances/<workflow_instance_id>/invoke
--header "Content-Type: <content_type>"
--header "api-key: <api-key>"
--data '{
"requestId": "<request_ID>",
"input": {
"send1": {
"recipient": "<recipient>",
"templateParams": "<template_params_object>"
},
"send2": {
"recipient": "<recipient>",
"templateParams": "<template_params_object>"
}
}
}'
Sample Request Format without Template Parameters
The following is the sample request format without template parameters:
curl -X POST --location https://api.in.kaleyra.io/v1/HXXXXXXX071IN/workflow/v1/instances/00112233-4455-6677-XXXX-XXXXXXXXXXXX/invoke
--header "Content-Type: application/json"
--header "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3"
--data '{
"requestId" : "e574XXXa-ef19-11ef-b02c-833eaXXXXf1d",
"input" : {
"send1" : {
"recipient" : "91806XXXXX81"
},
"send2" : {
"recipient" : "91806XXXXX81"
}
}
}'
Sample Request Format with Template Parameters
The following is the sample request format with template parameters:
curl -X POST --location https://api.in.kaleyra.io/v1/HXXXXXXX071IN/workflow/v1/instances/00112233-4455-6677-XXXX-XXXXXXXXXXXX/invoke
--header 'Content-Type: application/json'
--header "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3"
--data '{
"requestId" : "e574XXXa-ef19-11ef-b02c-833eaXXXXf1d",
"input" : {
"send1" : {
"recipient" : "91806XXXXX81",
"templateParams": {
"1" : "User",
"2" : "1 year",
"3" : "15% discount"
}
},
"send2" : {
"recipient" : "91806XXXXX81",
"templateParams": {
"1" : "User",
"2" : "1 year",
"3" : "15% discount"
}
}
}
}'
Sample Request Format with Special Template Parameters
The following is the sample request format with a special template parameter:
curl -X POST --location https://api.in.kaleyra.io/v1/HXXXXXXX071IN/workflow/v1/instances/00112233-4455-6677-XXXX-XXXXXXXXXXXX/invoke
--header 'Content-Type: application/json'
--header "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3"
--data '{
"requestId" : "e574XXXa-ef19-11ef-b02c-833eaXXXXf1d",
"input" : {
"send1" : {
"recipient" : "91806XXXXX81",
"templateParams": {
"#verification_code#" : "81XXX23"
}
},
"send2" : {
"recipient" : "91806XXXXX81"
}
}
}'
URL Parameters and Headers
Following is the list of parameters and headers with and without Template Parameters:
Parameter / Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
api_domain | String | valid domain | api.in.kaleyra.io | Yes |
sid | String | Account SID (Security Identifier). | HXAP16XXXXXX97IN | Yes |
workflow_instance_id | String | Unique ID of the workflow instance. This ID can be retrieved from the Fallback Page in the Kaleyra User Interface. | 00112233-4455-6677-XXXX-XXXXXXXXXXXX | Yes |
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. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
requestId | String | Unique request ID that you should set. Recommended is a Universally Unique Identifier (UUID), Globally Unique Identifier (GUID) or similar unique ID. Note: You cannot submit a request with the same request ID again. | e574XXXa-ef19-11ef-b02c-833eaXXXXf1d | Yes |
recipient | String | Unique ID of recipient. Phone numbers must include the country code, but without the + prefix. For example: "91806XXXXX81" (for an Indian number). | 91806XXXXX81 | Yes |
template_params_object | JSON Object | One or more template parameters specified as key-value pairs. Note: For more information, see Channel Agnostic Template Parameters. | Example: {"1": "user", "2": "1 year", "3": "15% discount"} | No |
Channel Agnostic Template Parameters
When you invoke a Fallback, template parameters are passed in a channel-agnostic format as key-value pairs.
For example, parameters may be passed as: {"1": "John", "2": "919620XXXXXX "}.
If your template body uses variables such as {#var#}, {{$1}}, or {{1}}, the parameters provided are resolved by their position rather than their names. However, before substitution, the values are reordered alphabetically by their keys. To avoid unexpected results, we recommend controlling the order explicitly by using keys with ascending numbers, either as plain numbers (for example, "1") or as prefixes (for example, "1_keyname"). This ensures that the values are inserted into the template in the intended order.
To avoid unexpected results, we recommend controlling the order explicitly by using keys with ascending numbers, either as plain numbers (for example, "1") or as prefixes (for example, "1_keyname"). This ensures that the values are inserted into the template in the intended order.
If the variables in the template are defined by name, such as {{name}} or {name} (for SMS only), the parameters provided are resolved based on the exact name. In this case, the template variables are replaced with the values of the keys that exactly match the variable names. For example, if an SMS template is defined as: "Here is your {OTP}", you would invoke the Fallback with: {"OTP": "123456"} as template Parameters.
Special Template Parameters
The Invocation API supports special template parameters. These parameters must be provided within the template_Params
object and formatted as: #parameter_name#
.
Note:
- If a template parameter with a special key is detected, then the message will be adjusted to match the appropriate format for the channel.
Special Template Parameter | Case | WhatsApp Result | SMS Result |
---|---|---|---|
# verification_code# | Authentication Template (OTP) | The WhatsApp message is sent as an Authentication Template. | If the SMS is of type OTP, then the verification code is provided as the first template parameter. |
# param_header# | WhatApp template with a header parameter | The WhatsApp template is sent with the value assigned to #param_header# replacing the variable in the template header. | The SMS is sent with #param_header# provided as a standard variable. |
# param_url# | WhatsApp template with a dynamic URL button parameter | The WhatsApp template is sent with the value assigned to #param_url# replacing the variable in the dynamic URL button. | The SMS is sent with #param_url# provided as a standard variable. |
Sample Success Response
The following success message appears with the status 202 Accepted:
202 Accepted
Content-Type: application/json
{
"requestId" : "brandSuppliedUniqueInvocationRequestId",
"timestamp" : "2025-02-14T15:37:08.018XXXXXXX",
"success" : true,
"status" : 202,
"message" : "Request accepted, execution will start soon",
"workflowInvocationId" : "4xU9cYRHXXXXXXBDmNVR1D",
"executionStatus" : "ACCEPTED"
}
Sample Failure Response
The following is the failure response for failed API call:
{
"requestId": "2e5XXXXXX-9ff9-45e9-8b3f-1eXXXXXXXXXX",
"timestamp": "2025-05-02T08:17:43.396XXXXXXX",
"success": false,
"status": 400,
"message": null,
"errors": [
"Workflow Instance [0cccf798-17b9-4a3f-9dad-f1XXXXXXXXXX] is not published."
],
"workflowInvocationId": "4THJKXXXXXXXXXnOf5jrNv",
"executionStatus": "REJECTED"
}
Updated about 5 hours ago