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_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.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 / HeadersData TypeDescriptionExampleMandatory?
api_domainStringvalid domainapi.in.kaleyra.ioYes
sidStringAccount SID (Security Identifier).HXAP16XXXXXX97INYes
workflow_instance_idStringUnique ID of the workflow instance. This ID can be retrieved from the Fallback Page in the Kaleyra User Interface.00112233-4455-6677-XXXX-XXXXXXXXXXXXYes
Content-TypeStringIndicates the format of the content the API will be processing.The only allowed value is application/JSONYes
api-keyStringAPI key generated from Kaleyra platform.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes
requestIdStringUnique 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-833eaXXXXf1dYes
recipientStringUnique ID of recipient. Phone numbers must include the country code, but without the + prefix. For example: "91806XXXXX81" (for an Indian number).91806XXXXX81Yes
template_params_objectJSON ObjectOne 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 ParameterCaseWhatsApp ResultSMS 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 parameterThe 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 parameterThe 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"
}