Send SMS (JSON/XML)
POST Method
The Send SMS JSON/XML API allows you to send the same message to multiple numbers or different messages to different numbers.
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 asSenderID
.
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
NA pod | api.na.kaleyra.ai |
API request to send SMS in JSON/XML
To send SMS in JSON/XML, use the <api_domain>/v1/<sid>/sms/json
endpoint with the following request method:
The following is the request format to send SMS with JSON:
curl -X POST "https://<api_domain>/v1/<sid>/sms/json" \
--header 'api-key: <api-key>' \
--header 'content-type: <content_type>' \
--data-raw '{
"channel": "<channel>",
"type": "<type>",
"source":"<source>",
"prefix": "<prefix>",
"time":"<time>",
"from": "<from>",
"body":"<body>",
"template_id":"<template_id>",
"entity_id": "<entity_id>",
"unicode": "<unicode>",
"callback_profile_id": "<callback_profile_id>",
"sms": [
{
"to": "<to>",
"from": "<from>",
"body":"<body>",
"template_id": "<template_id>",
"entity_id": "<entity_id>",
"unicode": "<unicode>",
"callback_profile_id": "<callback_profile_id>"
}
]
}'
The following is the sample request format to send SMS with JSON:
curl -X POST "https://api.in.kaleyra.io/v1/HXXXXXXX071US/sms/json" \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-raw '{
"channel": "SMS",
"type": "TXN",
"source":"API",
"prefix": "+1",
"time":"2021-02-02T12:58:00+05:30",
"from": "+91XXXXXXXXXX",
"body":"Hello! This is the request to send SMS in JSON format.",
"template_id":"912XXXXXXXX312",
"entity_id": "1356XXXXXXXX4312",
"unicode": "0",
"callback_profile_id": "SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5 ",
"sms": [
{
"to": "+91XXXXXXXXXX",
"from": "+91XXXXXXXXXX",
"body":"This is the SMS JSON format.",
"template_id": "912XXXXXXXXX12",
"entity_id": "1356XXXXXXXXX312",
"unicode": "0",
"callback_profile_id": "SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5"
}
]
}'
The following is the sample request format to send SMS with XML:
curl --location --request POST 'https://api.in.kaleyra.io/v1/HXXXXXXX071US/sms/xml' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/xml' \
--data-raw '
<?xml version="1.0" encoding="UTF-8"?>
<api>
<channel>sms</channel>
<type>TXN</type>
<source>API</source>
<prefix>+1</prefix>,
<time>2021-02-02T12:58:00+05:30</time>
<body>Hello! This is the request to send SMS in JSON format.</body>
<from>+91XXXXXXXXXX</from>
<template_id>912XXXXXXXX312</template_id>
<entity_id>1356XXXXXXXX4312</entity_id>
<unicode>0</unicode>
<callback_profile_id>SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5</callback_profile_id>
<ref_custom>
<ref_name>REF_Name</ref_name>
<ref_age>REF_AGE</ref_age>
</ref_custom>
<sms>
<to>+91XXXXXXXXXX</to>
<from>+91XXXXXXXXXX</from>
<body>This is the SMS JSON format.</body>
<template_id>912XXXXXXXXX12</template_id>
<entity_id>1356XXXXXXXXX312</entity_id>
<unicode>0</unicode>
<callback_profile_id>SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5</callback_profile_id>
<ref_custom>
<ref_name>john</ref_name>
<ref_age>25</ref_age>
</ref_custom>
</sms>
</api>'
Following is the list of parameters and data types supported for sending SMS with JSON/XML:
Parameter | Data Type | Description | Example | Mandatory |
---|---|---|---|---|
| String | Account SID (Security Identifier). | HXXXXXXX071US | Yes |
| Alphanumeric | API key generated from Kaleyra.io account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
| String | The format in which the data is sent. | application/json | Yes |
| String | API supports only SMS and the SMS will be rejected, if any other channel is passed. | SMS | No |
| String | If SMS is not provided or left empty, the default value will be MKTfor Indian customers and DEFAULT for customers from other regions.
| TXN | No |
| String | If value is not passed or kept empty, then the default value is shown as API. | API | False |
| String | Prefix field holds country code as a value. If defined it is applicable for all the numbers in the SMS node. | +1 | No |
| ISO | Specifies the time at which the message is sent to the recipient. | 2021-02-02T12:58:00+05:30 | No |
| String | Specifies the message content which needs to be sent. | Hello! This is the request to send SMS in JSON format. | No |
| String | Specifies the Template ID registered with DLT Platform. | 912XXXXXXXX312 | No |
| String | Specifies the Entity ID that is registered with DLT Platform. | 1356XXXXXXXX4312 | No |
| String | If the value is not passed in the Unicode, then the default is set to Auto. Supported values are Auto, 0, and 1. | 0 | No |
| String | The ID of the callback profile to be used for sending webhooks related to the SMS status to the customer's system. | SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5 | No |
| JSON/XML Object | Specifies the SMS node which contains individual SMS configuration. SMS node can be repeated in the payload. | For more information related to SMS Node Fields, see SMS Node Fields table. | Yes |
Following is the list of SMS object attributes:
Replace | Variable | Description | Example | Mandatory |
---|---|---|---|---|
| Numeric | Customer Mobile Number. | +91XXXXXXXXXX | Yes |
| String | Specifies the Sender ID assigned to the account from which the SMS is sent. | +91XXXXXXXXXX | No |
| String | Message content which needs to be sent. | This is the SMS JSON format. | No |
| String | Specify the Template ID registered with DLT Platform. | 912XXXXXXXX312 | No |
| String | Specifies the Entity ID that is registered with DLT Platform. | 1356XXXXXXXX4312 | No |
| String | If the value is not passed, then the default is set to Auto. Supported values are Auto, 0, and 1. | 0 | No |
| String | Specifies the Callback profile ID generated as per customer settings. | SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5 | No |
Note:
- While sending the type of OTP, only one element is allowed into the array
- The maximum number of elements in the SMS array is 1000.
Success Response
The following success response is received when the JSON script has the correct syntax:
{
"body": "Hello! This is the request to send SMS in JSON format.",
"createdDateTime": "2021-09-13 06:47:44+05:30",
"id": "be4XXXX3-24a7-428f-b5dd-f09XXXXc14fb",
"sms": [
{
"body": "This is the SMS JSON format.",
"from": "sample",
"message_id": "be4XXXX3-24a7-428f-b5dd-f0XXXXXX9c14:0",
"recepient": "91XXXXXXXXXX",
"template_id": "912XXXXXXXXX12"
},
{
"body": "This is the second message",
"from": "sample1",
"message_id": "be43XXXX-24a7-428f-b5dd-f0XXXXXX9c14:1",
"recepient": "91XXXXXXXXXX",
"template_id": "912XXXXXXXXX12"
},
{
"body": "This is the third message",
"from": "sample2",
"message_id": "be4XXXX3-24a7-428f-b5dd-f09XXXXXXXXc:2",
"recepient": "91XXXXXXXXXX",
"template_id": "912XXXXXXXXX12"
}
],
"source": "API",
"type": "TXN"
}
Failure Responses
The following failure responses are received when the JSON script has an incorrect syntax:
- The following failure response appears when a JSON request body is invalid (if some of the fields are not appropriate).
{
"error": {
"code": "E700",
"type": "VALIDATION_ERROR",
"parameter": "sms",
"message": "Please enter a valid JSON object",
"reference": "0"
}
}
- The following failure response appears when the user is trying to send the type of OTP to two or more recipients.
{
"error": {
"code": "E708",
"type": "VALIDATION_ERROR",
"parameter": "sms",
"message": "For type OTP you can send only 1 sms. Sms node must have only 1 object.",
"reference": "1"
}
}
- The following failure response appears when SMS object in the request is empty.
{
"error": {
"code": "E703",
"type": "VALIDATION_ERROR",
"parameter": "sms",
"message": "sms field is mandatory and cannot be empty",
"reference": "2"
}
}
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.
Updated 10 days ago