Create Callback Profile for Incoming SMS Messages

You must configure the Callback Profile for Incoming SMS Messages to receive notifications regarding all the incoming messages (including the message content) received to your registered business SMS number. You must first create a Callback Profile and then add the Callback Profile ID to the Receive SMS Configuration of your number.

To create a Callback Profile for Incoming SMS Messages, perform the following steps:

1. Follow the instructions under Create a Callback Profile section in Callback Profiles page.

Select the required HTTP method:

i. POST and
a. In the "Enter Endpoint" field, enter the endpoint (as shown in the following example) where you want to receive notifications:

https://<webhook_url>

b. Enter the following in the "Enter Endpoint" field under the Dynamic Variables section of the Request Body text area:

{
"source": "<source>",
"recipient": "<recipient>",
"description": "<description>",
"status": "<status>",
"status_trace": "<status_trace>",
"id": "<id>",
"kid": "<kid>",
"message": "<message>",
"keyword": "<keyword>",
"operator": "<operator>",
"circle": "<circle>",
"timestamp": "<timestamp>",
"parts[n]": "<parts[n]>"
}

Sample Callback Message

The following is an example of a callback triggered by an incoming text message received by an end user when POST is selected as HTTP method:

{
  "description": "Message has been sent",
  "id": "90eXXXXX-8865-4a96-85b6-4XXXXXXXXX48",
  "kid": "90e74b4c-8XXX-4a96-85b6-44XXXXXXX08",
  "recipient": "+91XXXXXXXXXX",
  "source": "91XXXXXXXXXX",
  "status": "SENT",
  "status_trace": "SENT",
  "message":"UNSUBSCRIBE THE OFFER message",
  "keyword":"SAMPLE",
  "operator":"JIO",
  "circle":"JIO ASSAM",
  "timestamp":"2025-04-17 18:35:20",
  "parts[n]":"SAMPLE"
}

The following table displays the parameter sent to your endpoint as part of the POST Callback message generated by Kaleyra system:

ii. GET and in the "Enter Endpoint" field, enter the endpoint as shown in the following example:

1. Text

   https://webhook-test.com/a2a6cee4XXXXXXXXXXfc57e5f8599228?to=<recipient>&id=<id>&status=<status>&message_id=<message_id>&sender=<sender>&type=<type>&ref=<ref>&ref1=<ref1>&ref2=<ref2>&ref_custom=<ref_custom>&msgid=<msgid>&flash=<flash>&total=<total>&source=<source>&price=<price>&iso_code=<iso_code>&delivered=<delivered>&submittime=<submittime>&sent_time=<sent_time>&country_name=<country_name>&campaign_name=<campaign_name>&length=<length>&units=<units>&type=<type>&description=<description>&recipient=<recipient>&status_trace=<status_trace>
   

   📘

   Note:

   • You need to add your own endpoint where you want to receive notifications (the one here is just an example).
   • You MUST add all the query parameters in order to get the information about the incoming message.
   • GET method is not the recommended one.

Sample Callback Message

The following is an example of a callback triggered by an incoming text message received by an end user when GET is selected as HTTP method:

source="918240XXXXXX"&recipient="91987XXXXXXX"&description="Message has been sent"&status="SENT"&status_trace="SENT"&id="90e74b4c-8865-4a96-85b6-4406e4XXXX48"&kid="90e74b4c-8865-4a96-85b6-4406eXXXXXXX"&message="SUBSCRIBE THE OFFER message"&keyword=SAMPLE&circle="Airtel-Karnataka"&operator="Airtel"&parts[1]="SAMPLE"

The following table displays the parameter sent to your endpoint as part of the GET Callback message generated by Kaleyra system:

Add the Callback Profile ID to the Receive SMS Configuration for your Number

To receive a callback about the incoming SMS messages, the VMN has to be associated with the callback profile ID configured in the Receive Message page.

you must ensure that the SMS number has an associated Callback Profile ID configured. You can do this while creating a new SMS number or you can edit the configuration for an existing number.

📘

Note:

You can use different callback profiles, each with a different endpoint, if needed for each business SMS number you have configured.

1. On the profile settings drop-down list, select the Callback Profiles option.
   The Callback Profiles page appears with all the existing Callback Profiles.

2. On the Callback Profiles page, hover over the Callback Profile ID that you want to copy and click .

3. Go to Channels and on the SMS card click Manage.

   

   The Sender ID tab details appear.

   
   

4. Click Receive Message tab.
   The list of Receive SMS Configurations page appears.

5. 

   Click New Configuration. The New Configuration page appears.

6. In the Configuration section, toggle Trigger URL button and select Callback ID as Trigger Type.

7. Select Callback Profile from the drop-down list that is used in the APIs to trigger the callback to receive an update about the message status (for example, Delivered).
8. Click Save. The configuration is created.

📘

Note:

You can view the created configuration under Receive Message > Logs page.