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

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

<SOURCE>

String

The source will be an API or Plugin for identifying from where the API is called.

API

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.


Did this page help you?