Invocation API

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

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.

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"
}