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
- Complete the KYC to access all the features in Kaleyra.io.
- Create an API Key. To view the API Key and the SID, see View API Key and SID.
- Create Callback Profile for SMS Channel to see how to create a callback profile for SMS channel with dynamic variables.
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:
| Parameter | Data Type | Description | Example/Numeric Format | Mandatory (Yes /No) |
|---|---|---|---|---|
<SID> | String | Account SID (Security Identifier) | HXIN169510844XXX | Yes |
<API_KEY> | String | API Key generated by Kaleyra.io | Aaf0dff8cd58cf99cba958f8941d3XXX0 | Yes |
<CONTENT_TYPE> | String | The format in which the data is sent. | application/x-www-form-urlencoded | Yes |
<BODY> | String | Message contents that need to be sent. | Your Kaleyra OTP is 5556. This is valid for 5 minutes. | Yes |
<TO_NUMBER> | String | Recipient's MSISDN in E.164 format. | +18830907XXX | Yes |
<TYPE> | String | Route type | TXN | Yes |
<SENDER> | String | Originator/Alphanumeric ID (default KLRHXA) | KLRHXA | Yes |
<TEMPLATE_ID> | Integer | Unique ID of the template (Only for Indian Customers) | 1107160129068911XXX | Yes |
<CALLBACK_PROFILE_ID> | String | Unique 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-6ed654272XXX | No |
<MESSAGE_ID> | String | Unique ID for each message. Basically, this message ID helps you to identify each message. | ebcccXXf-6311-4c52-b23d-afeXXX5fcXXX:1 | Optional |
<STATUS>(used in the callback call send from kaleyra) | String | The following are the status used: SENT, NOT-SENT, and UNDELIVERED. | SENT | Optional |
<STATUS_TRACE>(used in the callback call send from kaleyra) | String | Status trace of the message. | REJECTED-MULTIPART | Optional |
<DESCRIPTION>(used in the callback call send from kaleyra) | String | Description of the delivery Status. | No sender ID is allocated | Optional |
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.
Updated 6 months ago