Send the First SMS

POST Method

SMS is a simple and a cost-effective way to communicate with customers. Before starting to send the SMS APIs, make sure that you have configured the SMS channel in Kalyra.io. This section details how to send your first outbound SMS using an API request.

Base URL

<https://api.kaleyra.io/v1/><SID>

To send your first SMS, follow the below steps:

  1. Signup or log in to Kaleyra.io and create your API key.

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.

📘

Note:

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.

  1. API request to Send Your First SMS.

Request Format

To send your first SMS, use the /messages endpoints.

curl -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "api-key: <API_KEY>" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -d "to=<TO_NUMBER>" \
     -d "sender=<SENDER_ID>" \
     -d "type=MKT" \
     -d "body=Hello! This is my first SMS." \
     -d "source=API" \
     -d "ref=<OPTIONAL_PARAMETER>" \
     -d "ref1=<OPTIONAL_PARAMETER1>" \
     -d "ref2=<OPTIONAL_PARAMETER2>" \
     -d "callback=<CALLBACK_OBJ>"

📘

Note:

Make sure you replace the parameter values with the proper inputs in the above code.

Parameters and Variables

The following table describes the parameters used in the SMS API request.

ParameterData typeDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier)HXXXXXXX071USYes
TO_NUMBERIntegerRecipient's MSISDN+1XXXXXXXXXXYes
SENDER_IDStringOriginator/Alphanumeric ID (default KLRHXA)KLRHXAYes
API_KEYStringAPI Key generated by Kaleyra.ioAc4XXXXX21fYes
TEMPLATE_IDIntegerUnique ID of the template.

Note:
This is not a mandatory field. For IN customers, if the TEMPLATE_ID is not provided, then, ‘MKT’ or ‘DEFAULT’ type value is considered.
2xxxxxxxxxxxxNo
TYPEStringRoute typeMKT, DEFAULTYes
REF
(optional parameter)
String/IntegerInclude the contextual information in this parameter.
For Example: Name, Customer ID, and so on
Customer NameNo
REF1
(optional parameter)
String/IntegerInclude the contextual information in this parameter.
For Example: Name, Customer ID, and so on
Company NameNo
REF2
(optional parameter)
String/IntegerInclude the contextual information in this parameter.
For Example: Name, Customer ID, and so on
DesignationNo
CALLBACKObjectThis data allows Kaleyra to send back the statuses of the messages that you have sent. The callback URL can be accessed publicly.

For more information on callback, see the SMS callback page.
{
"url": "<https://webhook.site/0exxxxfd-axxc-4xx1-bxxe-cdxxxxxxxx70>

",
"method": "POST",
"header": {
"x-api-key": "qwxxxxxxxxxxxxxxxxdv",
"x-random-id": "23xxxxey"
},
"retry": {
"count": "3",
"interval": XXXX071US",
"0-4": "Yes",
"1-0": "TO_NUMBER",
"1-1": "Integer",
"
}
}

Note: Only url and method are mandatory attributes, others are optional.
Refer to the following table for the callback object attributes and the description.
No

The following table describes the callback object attributes.

FieldDescriptionMandatory?
URLThe endpoint to receive callback information.Yes
MethodMethod to receive callback in eg GET,POST.Yes
Retry Object
CountThe number of times the callback should be retried to send.No
IntervalThe time interval in seconds to try sending the callback.No
HeaderAdditional data required by the endpoint to process callback.No

Optional Parameters

Add the required contextual information to your SMS using the Optional Parameters. You can include up to three parameters in the above SMS API call, and each can have a maximum of 50 characters.

📘

Note:

For Example,

When you deliver a message to multiple customers, you can pass your own Message ID as optional parameters in the API call. This information is sent back in the callback from Kaleyra.io to your system for further reference.

You can also include information such as:

  • Campaign Name
  • Client Name
  • Client ID
  • Product ID and so on

Response Format

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

Success Response

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "body": "Hello! This is my first SMS.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

The following table describes the API Response parameters.

ParameterDescription
bodyThe message content that is delivered to the handset.
senderThe sender ID used to send the SMS.
typeThe message type. For example, Marketing(MKT/Default), Transactional ((TXN), OTP, TXND).
sourceThe source of the message. For example, API, Plugins.
template_IDThe template that is used by the Kaleyra customer.
IDThe unique ID of the API request.
createdDateTimeThe request time of the API in UTC.
total_CountThe number of contacts present in the API request.
message_IDThis is the unique ID for each mobile number.
recipientThe mobile number in the API request.
unicodeThis indicates if the customer is using message content as unicode or normal text(1/0/AUTO).
flashThis indicates if the customer wants to deliver the message as a Flash message or not (1/0).
ref,ref1,ref2These are the additional parameters the customers can use for their reference. These parameters will return the ‘callback response’.

Failure Response

The following failure response is 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."
  }
}

📘

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.

Sample Request

curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "api-key: Ac4XXXXX21f" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "to=+1XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "body=Hello! This is my first SMS."
     -d "source=API" \
     -d "ref=Campaign name" \
     -d "ref1=Client Name" \
     -d "ref2=Product ID" \
     -d "callback={"url":"https://webhook.site/0exxxxfd-axxc-4xx1-bxxe-cdxxxxxxxx70","method":"POST","header":{"x-api-key":"qwxxxxxxxxxxxxxxxxdv","x-randoem-id":"23xxxxey"},"retry":{"count":"3","interval":["10","10","10"]}}"

Two-way SMS for Customer Engagement

Kaleyra's Two-Way SMS API is designed to offer you 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.

Sample Request
curl --location --request POST '<host>/v1/HXXXXXXX071US/messages/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api-key: Ac4XXXXX21f' \
--data-urlencode 'to=196xxxxxx56' \
--data-urlencode 'body=Accepting number as sender test 1' \
--data-urlencode 'sender=917xxxxxx834' \
--data-urlencode 'type=MKT' \
--data-urlencode 'source=API' \
--data-urlencode 'callback={"url":"https://webhook.site/0exxxxfd-axxc-4xx1-bxxe-cdxxxxxxxx70","method":"POST","header":{"x-api-key":"qwxxxxxxxxxxxxxxxxdv","x-randoem-id":"23xxxxey"},"retry":{"count":"3","interval":["10","10","10"]}}'

📘

Note:

For Two-way SMS, the sender variable must be String/Numeric. For example +17XXXXXXXX4.