Send SMS using Template

SMS is a simple and cost-effective way to communicate with customers. An SMS template allows you to send messages using a predefined format. Using kaleyra.io API you can send SMS based on a pre-saved template. Also, you can create SMS templates based on your requirements. This topic provides details on how to send your SMS using a template through an API request.

Prerequisites

• Before sending the SMS, you must configure the SMS channel in kaleyra.io.
• After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
• Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
• You must have an approved SenderID or a specific number to be used as SenderID.

Base URL

https://<api_domain>/v2/<SID>

📘

Note:

You will be using the v2 version of the base URL. The new endpoint is an extension of the original API with the added functionality of sending messages using a template ID.

API Domain and Value

API request to send SMS using a Template

To send an SMS using a template, use the /sms endpoint with the following request method:

Request Format

curl --location --request POST 'https://<api_domain>/v2/<SID>/sms' \
--header 'api-key:<api-key>' \
--header 'Content-Type:<content-type>' \
--data '{
    "to": "<to>",
    "sender": "<sender>",
    "type": "<type>",
    "channel": "<channel>",
    "template_id": "<template_id>",
    "template_data": {
        "example_key0": "<example_key0>",
        "example_key1": "<example_key1>",
        "example_key2": "<example_key2>"
    },
     "callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX"
}'

Sample Request Format

Sample POST method request

curl --location --request POST '<https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/sms' \
--header 'api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type:application/json' \
--data '{
    "to": "+91XXXXXXXXXX",
    "sender": "KLRHXA",
    "type": "TXN",
    "channel": "SMS",
    "template_id": "101XXXXXX012",
    "template_data": {
        "example_key0": "John",
        "example_key1": "23.43",
        "example_key2": "USD"
    },
     "callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX"
}'

URL Parameters and Headers

Following is the list of parameters and headers to send the outgoing message request:

Following is the list of attributes to be used in the payload to send the outgoing message:

📘

Notes:

• For template_id, if the body parameter is passed together with a template ID and template data, then the Body will have priority, and the template ID and template data will have less priority.
• (Optional) Customers outside of India must fetch the content when using the template_id.

The following table describes the different attributes used for the template_data JSON object, please note that the attribute name is not static but must be the same name as the name given to the placeholders (also known as dynamic variables) used in the template:

📘

Note:

The following are the validations for template-based SMS API's:

• The template_data attribute will be validated for string size (maximum of 30 characters per value).
• A check is performed to ensure all keys in the template are included in template_data parameter.
• Users must provide either template_id or body. If a user provides a body in the request template_id and template_data will be ignored and we will give priority to the body.

Success Response

The following success response is received when the JSON script has the correct syntax:

{
    "sender": "KLRHXA",
    "type": "TXN",
    "source": "API",
    "template_id": "10xxxxxxxx12",
    "id": "75xxxxd2-8xx6-4xxa-bxxf-5axxxxxxxx95",
    "createdDateTime": "2023-11-10 04:00:24+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "75XXXXd2-8XX6-4XXa-bXXf-5aXXXXXXXX95:1",
            "recipient": "18XXXXXX268"
        }
    ],
    "error": {}
}

Failure Responses

The following failure responses are received when the JSON script has an incorrect syntax:

• The following failure response appears when the template ID is not available with no Body:

{
    "code": "E413",
    "message": "Invalid/incorrect inputs",
    "data": [],
    "error": {
        "body": "Either body or template_id must be specified.",
        "template_id": "Either body or template_id must be specified."
    }
}

• The following failure response appears when the value of the template data key is larger than 30 characters:

{
    "code": "E413",
    "message": "Invalid/incorrect inputs",
    "data": [],
    "error": {
        "template_data": "The template data values should be under 30 characters"
    }
}

Callback Response

When the template ID has variable parameters and the template data are not provided, in that case instead of a response, a user will receive a callback with the error and the status "NOT-SENT".

{
  "sender": "KLRHXA",
  "flash": "0",
  "type": "TXN",
  "total": "1",
  "source": "API",
  "message_id": "4axxxxe5-0xx5-4xx2-axxc-f0xxxxxxxxfd:1",
  "length": "0",
  "units": "0",
  "template_id": "101010101012",
  "recipient": " +18XXXXXXXX8",
  "status_trace": "INV-TEMPLATE-MATCH",
  "status": "NOT-SENT",
  "description": "Template not matching approved text.",
  "id": "4aXXXXe5-0XX5-4XX2-aXXc-f0XXXXXXXXfd",
  "ref_custom": "[]"
}

SMS Error Codes, SMS Status and Status Trace Codes

Refer to the following links for Error Codes, Status and Status Trace Codes:

• For information related to SMS error codes, see SMS Error Codes.
• For information related to SMS status and status trace codes, see SMS Status and Status Trace Codes.