Send the First SMS

POST Method

SMS is a simple and cost-effective way to communicate with customers. This section details how to send your first outbound SMS using 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>/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 the first SMS

To send your first SMS use the <api_domain>/v1/<sid>/sms endpoint with the following request method:

Request Format

The following is the request format to send the first SMS:

curl -X POST "https://<api_domain>/v1/<sid>/sms" \
     -H "api-key:<api-key>" \
     -H "Content-Type:<content-type>" \
     -d "to=<to>" \
     -d "sender=<sender>" \
     -d "type=<type>" \
     -d "unicode=<unicode>"\
     -d "flash=<flash>"\
     -d "time=<time>"\
     -d "prefix=<prefix>"\
     -d "body=<body>" \
     -d "ref_custom=['<ref_custom>']"\
     -d "callback_profile_id=<callback_profile_id>"

Sample Request Format

The following is the sample request format to send the first SMS:

curl -X POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
     -H "api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
     -H "Content-Type:application/json" \
     -d "to=+91XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "type=MKT" \
     -d "unicode=Auto"\
     -d "flash=1"\
     -d "time=2024-07-13T12:58:00+04:30"\
     -d "prefix=+91"\
     -d "body=Hello, this is your first SMS." \
     -d "ref_custom=['John','Doe']"\
     -d "callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX"

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	`HXAP16XXXXXX97IN`	Yes
`api-key`	String	API key generated from kaleyra.io account.	`Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3`	Yes
`content-type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`to`	String	Phone number of the end customer you want to send a message to.	`+91XXXXXXXXXX`	Yes (valid phone numbers only)
`sender`	String	Alphanumeric Sender ID displayed on recipient devices.	KLRHXA	Yes

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

Parameter	Data Type	Description	Example	Mandatory?
`type`	String	Route type. Note*: This is not a mandatory field. For customers in the Indian region, the available SMS Types are OTP, Transactional (TXN), Transactional DND (TXND), and Marketing (MKT). For Europe, America, and Singapore regions, only OTP and Default (to be used for Marketing and Transactional) route types are available.	MKT	Yes
`unicode`	String	Determines message encoding. Acceptable values are "AUTO", "0", or "1". If you know it is a unicode message, then use 1. If you know it is not a unicode message, then use 0. If you are not sure about the unicode, then use Auto.	"Auto"	No
`flash`	String	Determines if the message is a flash SMS. Acceptable values are "0" or "1". Use 1, if you want to send the message as a flash message else use 0.	"0"	No
`time`	ISO Date	The time at which the message should be sent. Must be in ISO date format YYYY-MM-DDTHH:MM:SS+HH:MM.	"2024-07-13T12:58:00+04:30"	No
`prefix`	String	Country code prefix. If the mobile number does not have a country code and you want to add it as a prefix you have the option to update it here.	"+91"	No
`body`	String	Body of the SMS. It is required irrespective of whether `template_id` is present or not.	"Hello, this is your first SMS."	Yes
`ref_custom`	List	It contains an array of max 5 values that will be available in detailed reports and callback associated to the message. The values inside the array can have a maximum of 50 lengths in strings.	["John","Doe"]	No
`callback_profile_id`	String	The callback profile ID of the callback profile to be used to send webhook to your system about SMS status updates. For more information related to callback profiles, see callback profiles page	IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX	Yes

Response Format

This section provides you the success and failure JSON response formats for different scenarios.

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "body": "Hello, this is your first SMS.",
  "createdDateTime": "2024-07-13T12:58:00+04:30",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "+91XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Failure Responses

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

{
  "code": "E401",
  "message": "SMS length is exceeding 4000 characters.",
  "error": {
    "body": "SMS length is exceeding 4000 characters."
  }
}

Two-way SMS for Customer Engagement

Kaleyra's Two-Way SMS API offers an easy and efficient way to communicate with your customers. It allows you to instantly send and receive messages through your choice of long or short codes.

If you have purchased a two-way SMS number, you must pass the same number as a Sender ID in the above API call to initiate a two-way conversation with your customers.

📘
Note:
The two-way SMS for customer engagement feature is available based on region. For example, it is available for customers registered in the EU and the SG regions. This feature is not available for customers registered in the IN region.

Sample Request Format

curl --location --request POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
--header "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
--header "Content-Type: application/json" \
--data-urlencode "to= +91XXXXXXXXXX" \
--data-urlencode 'body= Hello, this is your first SMS.' \
--data-urlencode 'sender= +917xxxxxx834' \
--data-urlencode 'type= MKT' \
--data-urlencode "ref_custom= ['John','Doe']"\
--data-urlencode "callback_profile_id= IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX"

📘
Note:
For Two-way SMS, the sender variable must be Numeric. For example, +917xxxxxx834.

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