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.

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.kaleyra.io/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 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.kaleyra.io/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.kaleyra.io/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>"
    }
}'

OR

curl --location --request GET '<https://api.kaleyra.io/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.kaleyra.io/v2/HXXXXXXX071US/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.kaleyra.io/v2/HXXXXXXX071US/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:

ParameterData TypeDescriptionMandatoryExample
sidStringAccount SID (Security Identifier).YesHXXXXXXX071US
api-keyStringAPI key generated from Kaleyra.io account.YesAxxxxxxxxxxxxxxxxxxxxxxxxxxxx3
content-typeStringThe format in which the data is sent.Yesapplication/json
toString or ArrayIt 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“]
Conditional9188XXXXXXXX
to-numberString or ArrayYou can use it as an alternative to to parameter. Required when to is not provided.Conditional9188XXXXXXXX
senderStringSender ID used for sending SMS. The sender must be in the form of a tag when used in template-based sending.Yes"KLRHXA"
portNumericThe port number to be used, if applicable.No8080
bodyStringBody of the SMS. It is required if template_id is not provided.Conditional"Test message with {name}"
unicodeStringDetermines message encoding. Acceptable values are "AUTO", "0", or "1".No"Auto"
flashStringDetermines if the message is a flash SMS. Acceptable values are "0" or "1".No"0"
campaign_nameStringName of the campaign. Must match regex pattern ^[\w-]*$.No"Summer_Sale"
ref, ref1, ref2StringCustom reference fields for the message, up to 150 characters each.No"referral_code"
timeISO DateThe 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_idStringTemplate 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 usetemplate_id.
Conditional"91231212123123"
template_dataJSON 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" }
channelStringThe communication channel used. No"SMS"
callbackJSON structureURL 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_identifierStringAn identifier for the template. template_identifier must exist as a tag if using template-based sending.No"101010101012"
template_paramsArrayAn identifier for the template. template_params must exist as a tag if using template-based sending.No{"customer_name": "John Doe"}
typeStringType of the SMS (for example, transactional). type must exist as a tag if using template-based sending.No"TXN", “TXND”, “MKT”
prefixStringCountry code prefix. prefix must exist as a tag if using template-based sending.No"+91"
timezoneStringTimezone 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.