Send Template Message with Dynamic Variables

The Send Template Message with Dynamic Variables uses template containing variable parts; each variable is a placeholder within the template that gets replaced with actual data for each recipient when the message is sent, allowing the same template to send personalized message to each given recipient.

📘

Note:
This feature is applicable only to customer onboarded in the India region.

• You must have an approved AgentID or a specific number to be used as AgentID.
• Templates must be approved in Kaleyra platform and in RCS ecosystem.

API request to Send Dynamic Template Message

To send Dynamic template message, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/messages endpoint with the following request method:

The following is the request format to send templates with dynamic variables using messageParams:

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/messages' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data-raw '{
  "from": "<from>",
  "to": ["<to>"],
  "templateId": "<template_id>",
  "ttlSeconds": <ttlSeconds>,
  "messageParams": [
    {
      "<first_variable_name>": "<first_variable_value>",
      "<second_variable_name>": "<second_variable_value>",
      "<last_variable_name>": "<last_variable_value>"
    }
  ]
}'

The following is the sample request format to send templates with Dynamic variables using messageParams:

curl --location --request POST 'https://rcs-api.in.kaleyra.io/v1/XXXXX6913850XXXX/rcs/messages'
--header 'Content-Type: application/json' \ 
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \ 
--data  { 
  "from": "rcs-vi-IN-Trans",
  "to": ["91XXXXXXXXXX", "91XXXXXXXXXX"],
  "templateId": "template-dynamic-1234",
  "ttlSeconds": "30",
  "messageParams": [
    {
      "firstName": "John",
      "dueAmount": "500",
      "dueDate": "2026-04-20"
    },
    {
      "firstName": "Jane",
      "dueAmount": "750",
      "dueDate": "2026-04-22"
    }
  ]
}'

The following is the list of attributes to be used in the payload to send Dynamic template message:

📘

Note:

Each object within the messageParams array contains a list of "<name>": "<value>" pairs, one for each variable in the template that needs to be replaced.

Please be aware that:

• Variables are replaced based on a match between the variable names in the template body and the names provided in the JSON request as the "<name>" attributes.
• Elements in the messageParams array must be in the same order as the recipient numbers in the to array. The first element personalizes the message for the first recipient, the second element for the second recipient, and so on.
• Any mismatch in one or both of the above may disrupt message personalization.

Following the request sample above, the following attributes are used in the payload (messageParams) to send a dynamic template message:

📘

Note:

You can pass additional parameters in messageparams based on your requirement, provided they are defined in the approved template.

{
    "code": "1200",
    "message": "Message Sent Successfully to provider",
    "data": {
        "to": ["91XXXXXXXXXX","91XXXXXXXXXX"],
        "messageId": "0c213560-47d1-46c4-a71d-d6XXXXXXXXXX"
    },
    "error": {}
}

{
"type":"ERROR",
"eventId":"5d951fc9-9d96-4971-96f0-aaXXXXXXXX3e",
"from":"91XXXXXXXXXX",
"to":"rcs-vi-IN-Trans",
"sentAt":"2026-02-19T12:36:28.421Z",
"messageId":"cb774c44-2205-4bf0-a754-b9a1XXXXXXX9",
"error":
{
"code":"CARRIER_ERROR",
"reason":"400-B-- Template not approved",
}
} 

{
"type":"ERROR",
"eventId":"bb81b327-e08e-4e39-8b0d-6XXXXXXXXXX0",
"from":"91XXXXXXXXXX",
"to":"rcs-vi-IN-Trans",
"sentAt":"2026-02-20T10:18:02.281Z",
"messageId":"ccec5381-b6bd-4faf-8bfc-09XXXXXXXXXX",
"error":
{
"code":"CARRIER_ERROR",
"reason":"400-C-- Template limit exceeded",
}
}