Callback Request using Callback Profiles

Before proceeding with the Callback Profiles option, you need to have a callback profile created. For more information on how to create callback profiles, see the Callback Profiles page.

The callback profile contains all the information needed for our system to send back information to your system. Example: Callback URL, HTTP method, headers, and so on.

📘

Notes:

  • The Callback profiles option also supports static authentication based on username and password, API KEY, or any other method that does not require dynamic fields.
  • If your callback URL requires authentication, you need to add all the needed headers and related values to your callback profiles.
  • Kaleyra.io will automatically retrieve this information when generating the HTTP call to your callback URL.

Base URL

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

Prerequisite

📘

Note:

To know all the callback profile IDs, go to Accounts Settings > Callback Profiles page. You can filter the callback profiles on the listing page with Callback Profile Name, HTTP Method, and Created Date range for accurate results.

Request Format

curl --location --request POST 'https://api.in.kaleyra.io/v1/<SID>/messages' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: <CONTENT_TYPE>' \
--data-urlencode 'body=<BODY_CONTENT>' \
--data-urlencode 'to=<TO_NUMBER>' \
--data-urlencode 'type=<CONTENT_TYPE>' \
--data-urlencode 'sender=<SENDER>' \
--data-urlencode 'template_id=<TEMPLATE_ID>' \
--data-urlencode 'callback_profile_id=<CALLBACK_PROFILE_ID>'

Sample Request Format

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXIN169510844XXX/messages' \
--header 'api-key: Aaf0dff8cd58cf99cba958f8941d30XXX' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'body=Your Kaleyra OTP is 5556. This is valid for 5 minutes.' \
--data-urlencode 'to=+18830907XXX' \
--data-urlencode 'type=TXN' \
--data-urlencode 'sender=KLRHXA' \
--data-urlencode 'template_id=1107160129068911XXX' \
--data-urlencode 'callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX'

Parameters and Data Types

Following is the list of parameters and data types supported and the attributes that could be added to the API call when requesting the Callback Profile ID:

ParameterData TypeDescriptionExample/Numeric FormatMandatory (Yes /No)
<SID>StringAccount SID (Security Identifier)HXIN169510844XXXYes
<API_KEY>StringAPI Key generated by Kaleyra.ioAaf0dff8cd58cf99cba958f8941d3XXX0Yes
<CONTENT_TYPE>StringThe format in which the data is sent.application/x-www-form-urlencodedYes
<BODY>StringMessage contents that need to be sent.Your Kaleyra OTP is 5556. This is valid for 5 minutes.Yes
<TO_NUMBER>StringRecipient's MSISDN in E.164 format.+18830907XXXYes
<TYPE>StringRoute typeTXNYes
<SENDER>StringOriginator/Alphanumeric ID (default KLRHXA)KLRHXAYes
<TEMPLATE_ID>IntegerUnique ID of the template (Only for Indian Customers)1107160129068911XXXYes
<CALLBACK_PROFILE_ID>StringUnique callback profile ID is set for each account for a callback. For more information related to callback profiles, see callback profiles page.IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXXNo
<MESSAGE_ID>StringUnique ID for each message. Basically, this message ID helps you to identify each message.ebcccXXf-6311-4c52-b23d-afeXXX5fcXXX:1Optional
<STATUS>
(used in the callback call send from kaleyra)
StringThe following are the status used:
SENT, NOT-SENT, and UNDELIVERED.
SENTOptional
<STATUS_TRACE>
(used in the callback call send from kaleyra)
StringStatus trace of the message.REJECTED-MULTIPARTOptional
<DESCRIPTION>
(used in the callback call send from kaleyra)
StringDescription of the delivery Status.No sender ID is allocatedOptional

Response Format

This section provides you with the JSON format that will be sent to your system in the Callback call.

Sample Callback Body (in case of POST method is selected for Callback)

{
  "sender": "TEST",
  "recipient": "919620838XXX",
  "type": "DEFAULT",
  "flash": 0,
  "total": 1,
  "source": "API",
  "price": "0.001354",
  "iso_code": "IN",
  "message_id": "ebcccXXf-6311-4c52-b23d-afeXXX5fc336:1",
  "country_name": "India",
  "campaign_name": "",
  "length": 5,
  "units": 1,
  "sent_time": "2022-04-05 09:55:50",
  "status_time": "2022-04-05 08:55:50+00:00",
  "status_trace": "REJECTED-MULTIPART",
  "status": "Undelivered",
  "description": "Validation fail [SMS over 160 characters]",
  "id": "ebccc6ff-6311-4XXc-b23d-afe6fXXXXXf6",
  "ref": "",
  "ref1": "",
  "ref2": ""
}

Sample Callback (in case of GET method is selected for Callback)

https://webhook.site/144e0a34-654e-4287-b8d1-16fa41ba7d42?sender=KALYRA&recipient=918867243XXX&type=OTP&flash=0&total=1&source=API&price=0.001711&iso_code=IN&message_id=84352649-f610-4fd7-XXXe-c163be9b1e&country_name=India&campaign_name=&length=54&units=1&sent_time=2022-04-12&status_time=2022-04-12&status_trace=REJECTD&status=Undelivered&description=SMS Rejected as the number is blacklisted by operator.&id=84352649-f610-4fd7-b7de-c163be9b1XXX&ref=&ref1=&ref2=

HTTP Status Code and Response Code

For more information regarding the HTTP Status Codes and Response Codes, see SMS Error Codes.