SMS Callback

POST and GET Method

Description

The callback function provides you a unique ID to verify the status and the timestamp of the message. You can also check the phone number to which the message has been sent.
The valid statuses are:

  • Sent
  • Delivered
  • Read
  • Failed

📘

Example

Callback URL: https: //webhook.site/22b91760-1da9-41d9-a806-1c681bb254fe?id=a2d4ef99-fa14-4487-ab3a-d245b65face611a4%3A2&phone_number=%20%201202XXXXXXX&status=delivered& timestamp=1580972783

In the above example, 'a2d4ef99-fa14-4487-ab3a-d245b65611a4%3A2' is your unique id; the
phone_number is '1202XXXXXXX'; status is 'delivered' and the timestamp is '1580972783'. if you get the status as Failed, a reason will show up.

You can make the HTTPS request via the GET and POST methods.

Base URL

"https://api.kaleyra.io/v1/"

To request a callback, follow the below steps:

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

Refer to the Create an API Key page for steps to create your API key.

📘

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.

2. API Command to request a callback

The following POST and GET method API commands let you request for an SMS callback.

Request Format

To request a callback use the /messages endpoint.

POST Method
curl --location --request POST 'https://api.kaleyra.io/v1/<SID>/messages' \
--H 'Content-Type: <CONTENT_TYPE>' \
--H 'api-key: <API_KEY>' \
--d 'to=<TO_NUMBER>' \
--d 'body=<BODY> ' \
--d 'sender=<SENDER_ID>' \
--d 'type=<MESSAGE_TYPE>' \
--d 'callback=<{"url":"https://webhook.site/16fed22f-4a79-4570-9c30-967b8520aca0","method" : "POST","header" : {"x-api-key" : "Apex test SMS callback","x-randoem-id" : "232y2uey"},"retry" :{"count":"3","interval":["10", "10","10"]}}'
GET Method
curl --location --request GET 'https://api.kaleyra.io/v1/<SID>/messages?to=<TO_NUMBER>&unicode=1&body=<BODY>&type=<MESSAGE_TYPE>&sender=<SENDER_ID>&source=ELOQUA&callback={%22url%22%20:%20%22https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254%22,%22method%22%20:%20%22GET%22,%22header%22%20:%20{%22x-api-key%22%20:%20%22qwfjagdfksdbsdvmnsdv%22,%22x-randoem-id%22%20:%20%22232y2uey%22},%22retry%22%20:{%22count%22:%223%22,%22interval%22:[%2210%22,%20%2210%22,%2210%22]}}' \
--H 'api-key: <API_KEY>' \
--H 'Content-Type: <CONTENT_TYPE>' \
--d ''

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

Below is the list of parameters and variables used:

Replace

Variable

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

True

CONTENT_TYPE

Alphabet

Indicates the format of the content the API will be processing.

application/json

True

API_KEY

String

The API Key that you have generated in the Kaleyra.io.

Ac4XXXXX21f

True

TO_NUMBER

Integer

Recipient's MSISDN.

+1XXXXXXXXXX

True

BODY

String

Body content.

Test on DLT

False

SENDER_ID

String

Originator/Alphanumeric ID (default KLRHXA).

KLRHXA

True

MESSAGE_TYPE

Alphabets

Format of the message.

Text

True

CALLBACK_URL

Object

The URL you want to receive the status of the message that is sent. This URL can be accessed publicly.

https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254

True

METHOD

String

Specifies the preferred method of receiving the SMS callback.

POST/GET

True

HEADER

String

Specifies any custom header that needs to be passed in the SMS callback request.

Test SMS callback

False

COUNT

Integer

Specifies the number of repeated attempts in case if SMS callback fails due to an error.

3

True

INTERVAL

Integer

Specifies the time interval in seconds between each callback retry. The number of interval values needs to be the same as the retry COUNT added as comma-separated values.

["10","10","10"]

True

Sample Request - POST

curl --location --request POST 'https://api-stgconsole.smsinfini.com/v1/HXAP166XXXXXX96IN/messages' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api-key: A7XXd254d0XXXXXXXXe72396XXXXXXXXa' \
--data-urlencode 'to=9188XXXXXXXX' \
--data-urlencode 'body="Your Kaleyra OTP is Schedule. This is valid for 5 minutes."' \
--data-urlencode 'sender=KALYRA' \
--data-urlencode 'type=MKT' \
--data-urlencode 'callback={"url" : "https://webhook.site/16fed22f-4a79-4570-9c30-96XXXXXXXca0","method" : "POST","header" : {"x-api-key" : "Apex test SMS callback","x-randoem-id" : "232y2uey"},"retry" :{"count":"3","interval":["10", "10","10"]}}' \
--data-urlencode 'template_id=1107160129XXXXXXX94'

Sample Request - GET

curl --location -g --request GET 'https://api-stgconsole.smsinfini.com/v1/HXAP1660XXXXX6IN/messages?to=918867243086&type=OTP&sender=KALYRA&template_id=1107160129068911217&callback={%22url%22%20:%20%22https://webhook.site/16fed22f-4a79-4570-9c30-967b8520aca0%22,%22method%22%20:%20%22POST%22,%22header%22%20:%20{%22x-api-key%22%20:%20%22Atul%20test%20SMS%20callback%22,%22x-randoem-id%22%20:%20%22232y2uey%22},%22retry%22%20:{%22count%22:%223%22,%22interval%22:[%2210%22,%20%2210%22,%2210%22]}}&body=Your%20Kaleyra%20OTP%20is%20AT007.%20This%20is%20valid%20for%205%20minutes.' \
--header 'api-key: A722d254d06646XXXXXXXXXXXXXX81e9a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw ''

3. Response Format

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

Success Response

POST Method
{
  "sender": "KALYRA",
  "recipient": "91xxxxxxxxxx",
  "type": "MKT",
  "flash": -1,
  "total": 1,
  "source": "ELOQUA",
  "price": "0.073427",
  "iso_code": "IN",
  "message_id": "5e2d08cc-c8e6-443d-8dde-a648435a6331:1",
  "country_name": "India",
  "campaign_name": "",
  "length": 19,
  "units": 1,
  "sent_time": "2020-10-07 04:23:35",
  "status_time": "2020-10-07 07:23:35+00:00",
  "status_trace": "REJECTD",
  "status": "Undelivered",
  "description": "SMS Rejected as the number is blacklisted by operator.",
  "id": "5e2d08cc-c8e6-443d-8dde-a648435a6331"
}
GET Method
{
"sender": "KALYRA",
"recipient": "91xxxxxxxxxx",
"type": "MKT",
"flash": -1,
"total": 1,
"source": "ELOQUA",
"price": "0.073427",
"iso_code": "IN",
"message_id": "6xxxxxxx-4xxx-4xxx-bxxx-6xxxxxxxxxxx:1",
"country_name": "India",
"campaign_name": "",
"length": 19,
"units": 1,
"sent_time": "2020-10-07 04:23:45",
"status_time": "2020-10-07 07:23:45 00:00",
"status_trace": "REJECTD",
"status": "Undelivered",
"description": "SMS Rejected as the number is blacklisted by operator.",
"id": "6xxxxxxx-4xxx-4xxx-bxxx-6xxxxxxxxxxx"
}

Failure Response

Invalid Sender ID

You have entered the Sender ID that is not allotted. Re-execute the command with the appropriate Sender ID.

{
  "sender": "Axxxxxxx",
  "flash": -1,
  "type": "MKT",
  "total": 1,
  "source": "API",
  "price": null,
  "iso_code": null,
  "message_id": "4xxxxxxx-xxxx-xxxx-bxxx-3xxxxxxxxxxx:1",
  "country_name": null,
  "campaign_name": "",
  "length": 21,
  "units": 1,
  "sent_time": null,
  "status_time": null,
  "recipient": "91xxxxxxxxxx",
  "status_trace": "SNDRID-NOT-ALLOTTED",
  "status": "Undelivered",
  "description": "No sender ID is allotted",
  "id": "4xxxxxxx-3xxx-4xxx-bxxx-3xxxxxxxxxxx"
}

Did this page help you?