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 as SenderID.

Base URL

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

Request Format

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>"
        }
    ]
}'

Sample Request Format

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"
        }
    ]
}'

Sample Request Format

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>'

Parameter and Data Types

Following is the list of parameters and data types supported for sending SMS with JSON/XML:

Parameter	Data Type	Description	Example	Mandatory
`sid`	String	Account SID (Security Identifier).	HXXXXXXX071US	Yes
`api-key`	Alphanumeric	API key generated from Kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`content-type`	String	The format in which the data is sent.	application/json	Yes
`channel`	String	API supports only SMS and the SMS will be rejected, if any other channel is passed.	SMS	No
`type`	String	If SMS is not provided or left empty, the default value will be MKTfor Indian customers and DEFAULT for customers from other regions. Supported Values: MKT,DEFAULT,TXND,TXN, andOTP*.	TXN	No
`source`	String	If value is not passed or kept empty, then the default value is shown as API.	API	False
`prefix`	String	Prefix field holds country code as a value. If defined it is applicable for all the numbers in the SMS node. Note: Priority will be given to numbers with a country code. The prefix will only be applied if the number does not include a country code.	+1	No
`time`	ISO	Specifies the time at which the message is sent to the recipient. The time must be specified in the below format: YYYY-MM-DDThh:mm:ss<Time_Zone>	2021-02-02T12:58:00+05:30	No
`body`	String	Specifies the message content which needs to be sent.	Hello! This is the request to send SMS in JSON format.	No
`template_id`	String	Specifies the Template ID registered with DLT Platform. Mandatory only for India-based company.	912XXXXXXXX312	No
`entity_id`	String	Specifies the Entity ID that is registered with DLT Platform. Mandatory only for India-based company.	1356XXXXXXXX4312	No
`unicode`	String	If the value is not passed in the Unicode, then the default is set to Auto. If you want to encode the body which is in Unicode, then value is set to 1. If you want to send SMS via JSON/XML API, without encoding the message content, then the value is set to 0. Supported values are Auto, 0, and 1.	0	No
`callback_profile_id`	String	The ID of the callback profile to be used for sending webhooks related to the SMS status to the customer's system. For more information related to callback profiles, see callback profiles page.	SG_074aXX38-2XXd-4e53-b5XX-b60c5XXXXXc5	No
`SMS`	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

Object of the "SMS" Array

Following is the list of SMS object attributes:

Replace	Variable	Description	Example	Mandatory
`to`	Numeric	Customer Mobile Number.	+91XXXXXXXXXX	Yes
`from`	String	Specifies the Sender ID assigned to the account from which the SMS is sent.	+91XXXXXXXXXX	No
`body`	String	Message content which needs to be sent. Note: If the body is not passed in the SMS object, then this will be considered.	This is the SMS JSON format.	No
`template_id`	String	Specify the Template ID registered with DLT Platform. Mandatory only for India-based company.	912XXXXXXXX312	No
`entity_id`	String	Specifies the Entity ID that is registered with DLT Platform. Mandatory only for India-based company.	1356XXXXXXXX4312	No
`unicode`	String	If the value is not passed, then the default is set to Auto. Supported values are Auto, 0, and 1.	0	No
`callback_profile_id`	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