Callback Request using Callback Profiles

POST and GET Methods

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. For example: Callback URL, HTTP method, Headers, and many more.

📘
Notes:

The Callback profiles option also supports static authentication based on username and password, API KEY, or any other method based on having kaleyra.io sending back to your system specific values as headers and 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.

The kaleyra.io will automatically retrieve this information when generating the HTTP call to your callback URL.

Prerequisites

Before sending the SMS, you must configure the SMS channel in kaleyra.io.
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.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
You must have an approved SenderID or a specific number to be used as SenderID.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

API request to send Callback using Callback Profiles

To request callback using callback profiles use the <api_domain>/v1/<sid>/sms endpoint with the following request method:

Request Format

The following is the request format to request a callback using callback profiles:

curl --location --request POST 'https://<api_domain>/v1/<sid>/sms' \
--header 'api-key:<api-key>' \
--header 'Content-Type:<content-type>' \
--data-urlencode 'to=<to>' \
--data-urlencode 'sender=<sender>' \
--data-urlencode 'body=<body>' \
--data-urlencode 'type=<type>' \
--data-urlencode 'template_id=<temlate_id>' \
--data-urlencode 'callback_profile_id=<callback_profile_id>'

📘
Note:
You can also use the GET method with the request format in this API.

Sample Request Format

The following is the sample request format to request a callback using callback profiles:

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms' \
--header 'api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type:application/json' \
--data-urlencode 'to=+91XXXXXXXXXX' \
--data-urlencode 'sender=KLRHXA' \
--data-urlencode 'type=MKT' \
--data-urlencode 'body= Your Kaleyra OTP is 55xx56. This is valid for 5 minutes.' \
--data-urlencode 'callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX' \
--data-urlencode 'template_id=101XXXXXX012'

URL Parameters and Headers

Following is the list of parameters and headers to send the outgoing message request:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	`HXAP16XXXXXX97IN`	Yes
`api-key`	String	API key generated from kaleyra.io account.	`Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3`	Yes
`content-type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`to`	String	Phone number of the end customer you want to send a message to.	`+91XXXXXXXXXX`	Yes (valid phone numbers only)
`sender`	String	Alphanumeric Sender ID displayed on recipient devices.	KLRHXA	Yes

Following is the list of attributes to be used in the payload to send message:

Parameter	Data Type	Description	Example	Mandatory?
`type`	String	Route type. Note*: This is not a mandatory field. For customers in the Indian region, the available SMS Types are OTP, Transactional (TNX), Transactional DND (TXND), and Marketing (MKT). For Europe, America, and Singapore regions, only OTP and Default (to be used for Marketing and Transactional) route types are available.	OTP	Yes
`body`	String	Body of the SMS. It is required if `template_id` is not provided.	"Your Kaleyra OTP is 55xx56. This is valid for 5 minutes."	Conditional
`callback_profile_id`	String	The callback profile ID of the callback profile to be used to send webhook to your system about SMS status updates. For more information related to callback profiles, see callback profiles page	IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX	Yes
`template_id`	String	Template ID for pre-registered templates. Required if the body is not provided. `template_id` must be 12 to 30 digits and exist as a tag. This is mandatory for Indian based company.	101XXXXXX012	Conditional
`message_id`	String	Unique ID for each message. Basically, this message ID helps you to identify each message.	ebcccXXf-6311-4c52-b23d-afeXXX5fcXXX:1	Conditional

Additional, attributes can be used in the payload to send message are following:

Parameter	Data Type	Description	Example	Mandatory?
`<status>` (used in the callback call sent from Kaleyra)	String	One of the following statuses can be used: SENT, NOT-SENT, and UNDELIVERED.	SENT	Conditional
`<status_trace>` (used in the callback call sent from Kaleyra)	String	Status trace of the message.	REJECTED-MULTIPART	Conditional
`description` (used in the callback call sent from Kaleyra)	String	Description of the delivery Status.	No sender ID is allocated	Conditional

📘
Notes:

For template_id, if the body parameter is passed together with a template ID and template data, then the Body will have priority, and the template ID and template data will have less priority.

(Optional) Customers outside of India must fetch the content when using the template_id.

The callback received from kaleyra.io to you for the request.

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

{
  "sender": "TEST",
  "recipient": "+91xxxxxxxxxx",
  "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": "2023-04-05 09:55:50",
  "status_time": "2023-04-05 08:55:50+00:00",
  "status_trace": "REJECTED-MULTIPART",
  "status": "SENT",
  "description": "Validation fail [SMS over 160 characters]",
  "id": "ebcccXXf-6311-4c52-b23d-afeXXX5fcXXX:1",
  "ref_custom": ""
}

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

https://webhook.site/14xxxx34-6xxe-4xx7-bxx1-16xxxxxxxx42?sender=KLRHXA&recipient=+91xxxxxxxXXX&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=2023-04-12&status_time=2023-04-12&status_trace=REJECTD&status=Undelivered&description=SMS Rejected as the number is blacklisted by operator.&id=ebxxxxff-6311-4XXc-b23d-afe6fXXXXXf6&ref_custom=

SMS Error Codes, SMS Status and Status Trace Codes

Refer to the following links for Error Codes, Status and Status Trace Codes:

For information related to SMS error codes, see SMS Error Codes.
For information related to SMS status and status trace codes, see SMS Status and Status Trace Codes.

Updated 12 days ago