Create SMS Callback Profiles using Dynamic Variables

You can create an SMS callback profile for the SMS status update in the K.io interface. While creating a callback profile for the SMS channel, the interface also provides a list of SMS related dynamic variables to select for which you want to receive information through the callback. The dynamic variables’ list serves as a ‘ready reckoner’ to add the callback variables without having to know the variable names. For each of the variables selected from the list, the callback will fetch the latest value for the given SMS into your system.

For information on how to use a callback profile in an SMS API request, see: Callback Request using callback profile.

📘

Note:

  • If you have multiple callback profiles created for different purposes, make sure you add the appropriate callback profile Id while calling the SMS API requests.
  • A callback profile created for the SMS channel cannot be used for other channels.
  • Once a callback profile is created for SMS, you can only edit the dynamic variables or delete the profile, but you cannot change the profile to a different channel.

To create an callback profile for receiving updates about SMS status :

  1. Navigate to the profile settings drop-down list and select the Callback Profiles option.

    The Callback Profiles page appears.

  2. On the Callback Profiles page, click Add New.
    The Add Callback Profile window appears.

  1. Perform the following steps to add all the relevant information in the ‘Add callback profile’ page.
    1. In the Title field, enter a title for the callback profile. This is a mandatory field.
    2. From the Select Channel API list, select the option ‘SMS - callback dynamic variables and types from SMS’ to create a callback profile to be used to receive back updated information about the SMS status.
    3. Once you select the option ‘SMS - callback dynamic variables and types form SMS’ in the previous step, the Events for the selected channel field is automatically set to the option ‘SMS Send’.
    4. In the HTTP Method field, select a method for which the callback is created.
      The options are: POST, GET, PUT, and DELETE. Only POST and GET methods are supported for the SMS channel.
    5. In the Enter Endpoint field, enter the URL at which the callback information should be received.
    6. In the Dynamic Variables field, click View to view and select the dynamic variables for the selected channel. The dynamic variables represent all the possible information that you can retrieve about the SMS as part of the callback that kaleyra.io will send to your system. You may select all of them, or only the fields you are interested in.
      The List Dynamic Variables window appears.

In the List Dynamic Variables window,

  • To select all the dynamic variables, click Select All or manually select the dynamic variables check-boxes that you want to receive in the callback sent from Kaleyra to your system.
  • After selecting the variables, click Copy to Clipboard.
  • Click ‘X’ (CLOSE) on the window to close the window.
  • Using the mouse, right click and paste the dynamic variables either in the Request Body field (POST method) or at the end of the Endpoint URL as query parameters (GET method).
  1. In the Headers field, enter the key-value pair values to add additional information to be added to the HTTPS request generated from Kaleyra to your system, for example, authentication details.
    Use the +Add more button to add multiple Header fields.
    For information on basic authentication, see: Basic authentication.

  2. Use the Enable Encryption toggle button to enable encryption of the callback information.

  3. When you enable this toggle button, the Algorithm, Key, and the Initialization Vector, and Parameters fields appear.

  4. Enter values in these fields. To know more about these fields, see: https://developers.kaleyra.io/docs/callback-profiles-in-accountssettings

  5. Use the Enable Callback Required Options toggle button to enable the Response Message field and enter a text as the callback response message.

  6. To check if the callback profile that you have created is ok, click Test.

  7. After filling in all the details, click Save to save the callback profile for the selected channel with the specified dynamic variables.
    Once you save the callback profile on the UI, you can see the callback profile ID that can be used in the SMS API requests to receive updates about the SMS status.

    The following table shows the field descriptions on the Add Callback profile window.

ColumnDescriptionExample
TitleThe name of the SMS callback profile.
You can use the callback title for searching the callback profiles.
SMS-campaignSMS - callback dynamic variables and values
Selected Channel APIThe channel for which the callback profile is created.-
Events for the selected channelThe events of the selected channel for which the callback information is obtained.
The relevant information for the selected event will be received using the callback.
SMS Send
HTTP MethodThis section provides the options to select the HTTP methods for the SMS channel APIs.
Select MethodThe options are: GET, POST, PUT, and DELETE.
Note:
The dynamic variables that you select get added as the query string parameters in the endpoint for the GET method.
The dynamic variables get added in the body of the JSON request for the POST method.
PUT or DELETE methods are not supported for SMS callback profiles.
POST
Enter endpointThis is the URL to which the callback data is returned.https://webhook.site/ae4bdcb3-a524-47e9-8eac-ef4cee045635]
Dynamic variablesAll the relevant dynamic variables for the SMS channel are listed here.
You can select the dynamic variables for which you want to receive the values through the callback.
The list of dynamic variables is the same for POST, GET methods.
Note: See the table below for dynamic variables descriptions.
status
Headers (Optional)The header information should be given as a key-value pair.
Use these fields to add any additional HTTP headers and related values you want to receive in the callback.

For example:
1)Use Headers for authentication purposes using the api-key.
2)Use Headers to indicate how the callback response should be presented using the content_type.
api-key:A71151f2c0ac28bb395016083d40a178a
Enable EncryptionThis toggle button is to enable encryption for the callback information. When this option is enabled, the callback data is encrypted. Use this feature to secure the callback data.For information on encryption algorithm and the related fields for this feature, see:
Callback Profiles page.
Enable Callback Required OptionThis toggle button is to enable and enter the response message for the chatbot services.
The chatbots can be controlled using the APIs and the API callback information can be used for message customization, status reporting and so on.
"The callback option is enabled.".

The following table shows the dynamic variables' descriptions with examples.

Dynamic variableDescriptionExample
flashIndicates if the SMS is a flash message or not (1/0). ‘1’ means the SMS is sent as a flash message and ‘0’ means the SMS is not a flash message.1
sent_timeIndicates the time at which the SMS is sent. This is based on the country specified using the iso_code.2023-05-17 12:05:14
totalThe total SMS units sent on a given day.1
sourceThe source of the request to send the SMS.
For example, API or campaign.
API
senderThis is the sender ID. A Sender ID is a unique name or standard mobile number that shows in the “from” field of your text messages on your phone. It could be a phone number, an alpha-numeric, an alphabetic, or a numeric alias.abc
priceThe unit price charged for the SMS based on the currency of the account.0
iso_codeThe country specific code of the SMS recipient.IN
country_nameThe country name(region) to which recipient's mobile number is associated.India
campaign_nameThe name of the campaign through which the SMS is sent.
Note: If the SMS is sent through a campaign, the campaign name is shown; if the SMS is sent through an API request, the value provided in the campaign_name field will be shown in this field.
test_camp
lengthThe length of the SMS in characters.12
unitsThe number of units billed for SMS service. The value '1' means that the whole text has been sent as one single SMS and a value more than '1' means that the SMS text has been sent in several concatenated SMS.1
typeThe SMS type. The options are OTP, TXN, or MKT.OTP
idThe ID represents the campaign part of the message.
If the same API request has multiple mobile numbers, the id field represents all the mobile numbers to which the message is sent.
e097772a-cd55-4f00-af4f-b7b1433347f8
descriptionThe description of the message.Message successfully delivered to the user
statusThe delivery status of the SMS.Delivered
message_idThe message id represents the ID> :
<order_of_mobile_in_campaign>
(id : order of the mobile number in the campaign) as shown in the example column.
e097772a-cd55-4f00-af4f-b7b1433347f8:1
recipientThe recipient phone number to which the message has been sent.9170227xxxxx
status_traceThis is the sub-status of the SMS that further helps understand more about the delivery status.DELIVRD
ref, ref1, & ref2These are the additional parameters the customers can use for their reference. These parameter values will be returned in the ‘callback response’.product name