Callback Profiles

Using the 'Callback Profiles' feature, you can create callback profiles to receive essential information and updates about various aspects such as SMS status, WhatsApp delivery status, and incoming WhatsApp messages.

This documentation will guide you through the process of leveraging callback profiles to enhance your communication capabilities.

Callback Profile Creation

You can create a callback profile tailored to your specific requirements. A callback profile offers a set of common options including the HTTP method to send the updates to your designated endpoint. The interface provides the flexibility to add additional HTTP headers to be included in the callback for validation purposes as well as for Basic and Advanced Authentication. All callbacks sent from the Kaleyra platform to our endpoint are encrypted in transit using TLS, to ensure content security further, you can encrypt the callback information as per your preferences. Further, you can configure specific attributes within each callback profile to receive the desired information at your endpoint.

The Callback Profiles user interface simplifies the creation of channel- or purposes-specific callback profiles, such as those for receiving messages or template status updates. The interface provides a list of relevant attributes you can receive back at your endpoint based on the selected channel and the events. You can select and incorporate all or just a part of these attributes into the callback profile effortlessly.

Using a Callback Profile ID

After creating a callback profile, a unique 'callback profile ID' is generated. You can use this callback profile ID for configurations within the UI and in your API requests, whenever you require to receive real-time updates related to a specific resource (for example, a recently sent SMS).

📘

Note:

To know the channel specific information, visit the following pages.

• SMS Channel - SMS Send event
• Email Channel - email Gateway APIs
• WhatsApp Channel - Incoming and outgoing messages
• Default - no channel selected (generic callback).

Create a Callback Profile

A callback profile creation includes the following steps.

To create a callback profile, perform the following steps:

1. On the profile settings drop-down list, select the Callback Profiles option.

   

   The Callback Profiles page appears.

2. Click Add New.
   The Add Callback Profile page appears.

3. In the Title field, enter the title of the Callback profile. This title can be used to search for callback profiles.
4. From the Select Channel API list, select a channel.
   The available options are:

• Voice - callback dynamic variables and types from Voice – You can use this option to create a callback profile to get updates about the status of a voice call using the dynamic variables.
• SMS - callback dynamic variables and types from SMS - You can use this option to create a callback profile to get updates about the status of a submitted SMS.
• email - Email Gateway APIs - You can use this option to create a callback profile to get updates about the status of a submitted email.
• whatsApp - WhatsApp Callbacks - You can use this option to create a callback profile to get updates about Message status, Incoming messages, Payment status, Message Template status update, and Phone number quality update.
• Default - No channel selected - This is the default option. Note: Select this option when you need to create a callback not specific to any channel or for a channel still not available in the list.

5. On selecting a channel other than the Default option, the Events for the selected channel field is enabled.
   The currently supported events for the channels are:

• “Voice” for Voice channel.
• "sms-send" for SMS channel.
• "email-send" for the Email channel.
• “message_status”, “incoming_message”, “payment_status”, “message_template_status_update”, and “phone_number_quality_update” for the WhatsApp channel.
• The field is disabled when you select the default option.

6. From the HTTP Method dropdown list, select the method you want Kaleyra platform to use to call your configured endpoint.

   📘

   Note:

   The suggested methods to be used for callback are GET and POST.

   1. GET: Use the GET method to retrieve information from the given server using a given URL:

      1. In the Enter Endpoint field, enter the URL at which the callback information should be received.

      2. 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 as part of the callback that the Kaleyra platform will send to your system. You may select all of them or only the fields you are interested in.
         The List Dynamic Variables pane appears on the right side of the page.

         

      3. 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.

      4. After selecting the variables, click Copy to Clipboard.

      5. Click ‘X’ (CLOSE) on the top-right of the pane to close it.

         

      6. Using the mouse, right-click and paste the dynamic variables at the end of the Endpoint URL as query parameters (GET method).

         
   2. POST: Use the POST method to send data to the server.

      1. In the Enter Endpoint field, enter the URL at which the callback information should be received.

      2. 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 the Kaleyra platform will send to your system. You may select all of them or only the fields you are interested in. The List Dynamic Variables pane appears on the right side of the page.

         

      3. 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.

      4. After selecting the variables, click Copy to Clipboard.

      5. Click ‘X’ (CLOSE) on the top-right of the pane to close it.
         Also, if you have a dynamic variable, you use it for the POST response. For example,

         https://webhook.site/93xxxx0d-5xxb-4xx0-bxx8-6axxxxxxxx46,
         "body":{"name":"name",
         "phone":"<whatsapp_number>",
         "address":{"formatted_address":"<address.formatted_address>" }
         } 

         

      6. Using the mouse, right-click and paste the dynamic variables in the Request Body field (POST method).

7. From the Retry drop-down, select the number of retries that Kaleyra Platform will perform in case the first callback receives a failure response or no response from your endpoint. You have the option for 0, 1, and 2. If you select either 1 or 2 retries, then you must enter the Time Interval in secs and the Timeout in milli-secs values. For assistance with more than two retry attempts, you can contact the Support team.

📘

Note:

The following are the retries according to channels:

• SMS - max 3 retries, 10s interval between retries.
• WhatsApp - max 4 retries, 60s interval between retries.
• Voice - max 4 retries, 60s interval between retries.
• Email - max 4 retries, 60s interval between retries.

For the Default priority, the Time Interval increases exponentially after each failed attempt. The formula for the delay: Delay = Initial Delay×(2^retry_count)

If the initial delay is 60 seconds and we allow up to 2 retries:

8. In the Headers field, enter values as Key-Value pairs. Use the Header fields to include additional information on the HTTPS request generated by Kaleyra for your system.

• Use the Headers field for authentication purposes. For example: API-KEY-based authentication or Basic authentication. For more information on basic authentication, see Basic Authentication.
• Use the Headers field to indicate how the callback response should be presented using the “Content Type”.

9. (Optional) Click the Enable Encryption toggle button. The fields related to encryption are displayed. This is an optional field. The Algorithm, Key, Initialization Vector, and Parameters fields appear. To know more about these fields, see Callback Encryption.

10. The Enable Callback Required Options is required only if you are using the ones provided by the Kaleyra Platform itself. To enable the Response message field and enter a text as the callback response message, toggle the Enable Callback Required Options button. For more information on advanced authentication fields, see Callback Advanced Authentication.
11. Click Test to send a callback to your endpoint based on the configuration just set in the callback profile to see if the callback is working as expected.
12. Click Save to save the callback profile in your kaleyra.io account. The confirmation message Callback Profile has been created successfully appears.

Callback Reports

The Kaleyra platform enables you to get automated Callback reports through email. If you enable the Callback Report, you will receive an email with the count of all failed and delivered callbacks at the selected frequency. You have the option to enable the Callback Report from the Notification page in Settings. After successfully enabling the Callback Report, you get the email based on the selected frequency (daily, weekly, or monthly).

To know how to enable the Callback Reports, see: Callback Reports.

Edit a Callback Profile

You can edit the callback profile after you have successfully created it.

To edit a callback profile, perform the following steps:

2. Click the ellipsis icon corresponding to the callback profile and select the Edit option. The Edit Callback Profile pane appears on the right side of the page.

3. Edit the details as required and click Save. The confirmation message Callback Profile has been updated successfully appears.

Duplicate a Callback Profile

Instead of creating a callback profile from scratch, you can duplicate the existing callback profiles. When you duplicate a callback profile, a new Callback ID will be auto-assigned to the copied callback profile and the name of the callback profile will be prefixed with Copy-. You can edit the existing details while copying the callback profile.
To create a copy of a callback profile, perform the following steps:

2. Click the ellipsis icon corresponding to the callback profile and select the Duplicate option. The Duplicate Callback Profile pane appears on the right side of the page.

3. Edit the callback profile details as required and then click Save. The confirmation message Callback Profile has been created successfully appears.

Delete a Callback Profile

You can delete the callback profile that has been successfully created.

To delete a callback profile, perform the following steps:

2. Click the ellipsis icon corresponding to the callback profile and click Delete.
   The Confirmation message pop-up appears.

3. Click Yes, Delete to delete the callback profile. A success message is displayed indicating that the callback profile has been deleted.

📘

Note:

A deleted callback profile cannot be restored.

Re-trigger a Failed Request

You can re-trigger a failed request from the callback profiles page.

To re-trigger a failed request sent using the information of a given callback profile, perform the following steps:

2. Click the ellipsis icon corresponding to the callback profile and select the Re-trigger failed requests option. The Confirmation message pop-up appears.

3. Click the Retrigger to retrigger the callback profile. A success message is displayed indicating that the callbacks are retriggered.

📘

Note:

All stored failed callbacks will be resent to the configured endpoint based on the configuration of the selected callback profile.

Disable a Callback Profile

You can disable a callback profile. After you disable the callback profile, you will no longer receive callback responses for campaign messages. You have only the option to edit, delete, and enable the callback.

To disable a callback profile, perform the following steps:

2. Click the ellipsis icon corresponding to the callback profile and select the Disable option. The Are you sure to disable this? message pop-up appears.

3. Click Disable to disable the callback profile. A success message is displayed indicating that the callback profile has been disabled. The disabled callback profile will be marked as Disabled.

📘

Note:

• If you add a disabled callback profile ID in your API call, then no callback will be triggered to your endpoint.
• You can enable a callback profile at any time you want.

Enable a Callback Profile

Any disabled callback profile can be enabled and used again.

To enable a callback profile, perform the following steps:

2. Click the ellipsis icon corresponding to the callback profile and select the Enable.
   The Are you sure to enable this? message pop-up appears.

3. Click Enable to enable the callback profile. A success message is displayed indicating that the callback profile has been enabled.