Send SMS using Template

POST and GET Methods

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's API you can send SMS with a template. Also, you can create SMS templates based on your requirements. This section details how to send your SMS using a template through an API request.

📘
Notes:

It is recommended to use /sms endpoints instead of /message endpoints for more efficient API requests and responses.

For North America (NA) pod users, use /sms endpoints for SMS API services provided by Kaleyra platform.

Prerequisites:

Before sending the SMS using the template, you must configure the SMS channel in Kalyra.io.
Refer to the Create an API Key page for steps to create your API key. To view the API Key and the SID, see View API Key and SID.
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.

Base URL

https://<api_domain>/v2/<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

📘
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 request to send SMS using a Template

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

Request Format

POST method request format

curl --location --request POST '<https://<api_domain>/v2/<sid>/messages' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--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": {
        "url": "<callback_url>",
        "method": "<callback_method>"
    }
}'

GET method request format

curl --location --request GET '<https://<api_domain>/v2/<sid>/messages' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "to": "<to>",
    "sender": "<sender>",
    "type": "<type>",
    "template_id": "<template_id>",
    "template_data": {
        "customer_name": "customer_name"
    },
    "callback": {
        "url": "<callback_url>",
        "method": "<callback_method>"
    }
}'

curl --location --request GET '<https://<api_domain>/v2/<sid>/messages?to=<to>&sender=<sender>&template_id=<template_id>&type=<type>&template_data={“customer_name”:”customer_name”}&callback={“url”:”<callback_url>”,”method”:”<callback_method>”}' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json'

Sample Request

Sample POST method request

curl --location --request POST '<https://api.in.kaleyra.io/v2/HXXXXXXX071IN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+821XXXXXX268",
    "sender": "KLRHXA",
    "type": "TXN",
    "channel": "SMS",
    "template_id": "1234XXXXXX997",
    "template_data": {
        "example_key0": "John",
        "example_key1": "23.43",
        "example_key2": "USD"
    },
    "callback": {
        "url": "<https://webhook.site/8dXXXXd6-1XX2-4XXc-aXXa-12XXXXXXXX4d>",
        "method": "GET"
    }
}'

Sample GET method request

curl --location --request GET '<https://api.in.kaleyra.io/v2/HXXXXXXX071IN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+821XXXXXX268",
    "sender": "KALYRA",
    "type": "TXN",
    "template_id": "101XXXXXX012",
    "template_data": {
        "customer_name": "Jean"
    },
    "callback": {
        "url": "https://webhook.site/8dXXXXd6-1XX2-4XXc-aXXa-12XXXXXXXX4d",
        "method": "GET"
    }
}'

Parameters and Data Types

Following is the list of parameters and data types supported:

Parameter	Data Type	Description	Mandatory	Example
`sid`	String	Account SID (Security Identifier).	Yes	HXXXXXXX071IN
`api-key`	String	API key generated from Kaleyra.io account.	Yes	Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3
`content-type`	String	The format in which the data is sent.	Yes	application/json
`to`	String or Array	It contains a phone number, Numbers Separated by “,“ comma OR It can have a list of numbers in an Array. Example 1: “9188XXXXXXXX“ Example 2: “9188XXXXXXXX, 9188XXXXXXXX“ Example 3: [“9188XXXXXXXX”, “9188XXXXXXXX“]	Conditional	9188XXXXXXXX
`to-number`	String or Array	You can use it as an alternative to `to` parameter. Required when `to` is not provided.	Conditional	9188XXXXXXXX
`sender`	String	Sender ID used for sending SMS. The sender must be in the form of a tag when used in template-based sending.	Yes	"KLRHXA"
`port`	Numeric	The port number to be used, if applicable.	No	8080
`body`	String	Body of the SMS. It is required if `template_id` is not provided.	Conditional	"Test message with {name}"
`unicode`	String	Determines message encoding. Acceptable values are "AUTO", "0", or "1".	No	"Auto"
`flash`	String	Determines if the message is a flash SMS. Acceptable values are "0" or "1".	No	"0"
`campaign_name`	String	Name of the campaign. Must match regex pattern ^[\w-]*$.	No	"Summer_Sale"
`ref`, `ref1`, `ref2`	String	Custom reference fields for the message, up to 150 characters each.	No	"referral_code"
`time`	ISO Date	The time at which the message should be sent. Must be in ISO date format Y-m-d\TH:i:sP.	No	"2021-02-02T12:58:00+05:30"
`template_id`	String	Template ID for pre-registered templates. Required if the body is not provided. `template_id` must be 12 to 30 digits and exist as a tag. Notes*: Body will have priority and template ID and template data will have less priority. Customers from India can use the Template ID to get the content within a template. (Optional) Customers except India have to fetch the content when they use`template_id`.	Conditional	"91231212123123"
`template_data`	JSON structure (Key-Value pair)	Data to replace template placeholders. `template_data` must be a key-value pair JSON structure with each value under 30 characters.	No	`"{ "Key1": "value1", "Key2": "value2" }`
`channel`	String	The communication channel used.	No	"SMS"
`callback`	JSON structure	URL for callbacks. `callback` must exist as a tag if using template-based sending.	No	`"callback": { "url": "<https://webhook.site/8dXXXXd6-1XX2-4XXc-aXXa-12XXXXXXXX4d">, "method": "GET" }`
`template_identifier`	String	An identifier for the template. `template_identifier` must exist as a tag if using template-based sending.	No	"101010101012"
`template_params`	Array	An identifier for the template. `template_params` must exist as a tag if using template-based sending.	No	`{"customer_name": "John Doe"}`
`type`	String	Type of the SMS (for example, transactional). `type` must exist as a tag if using template-based sending.	No	"TXN", “TXND”, “MKT”
`prefix`	String	Country code prefix. `prefix` must exist as a tag if using template-based sending.	No	"+91"
`timezone`	String	Timezone for the message. `timezone` must exist as a tag if using template-based sending.	No	"Asia/Kolkata"

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

The template_dataattribute 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 user provides body in the request temaplate_id and template_data will be ignored and we will give priority to the body.

Sample Success Response

The following success message appears with status 202 Accepted:

{
    "sender": "KALYRA",
    "type": "TXN",
    "source": "API",
    "template_id": "101010101012",
    "id": "75224ad2-8e86-491a-ba5f-5a72c07a3795",
    "createdDateTime": "2023-11-10 04:00:24+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "75XXXXd2-8XX6-4XXa-bXXf-5aXXXXXXXX95:1",
            "recipient": "18XXXXXX268"
        }
    ],
    "error": {}
}

Sample Failure Response

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". The reason is that you have to start processing the SMS before you validate it because at the time of sending the request, you might not know the content of the template ID.

{
  "sender": "KALYRA",
  "flash": "0",
  "type": "TXN",
  "total": "1",
  "source": "API",
  "message_id": "4aca0ce5-0495-4ca2-ab2c-f09834461efd: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": "[]"
}

📘
Note:
In case of an error, ensure that the parameter values are correct in the above code. Refer to the SMS Error Codes page for detailed information.

Updated 13 days ago