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 kaleyra.io 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:

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.
   You can use the Title field to search for callback profiles.
4. From the Select Channel API list, select a channel.
   The available options are:

• 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.
• 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—Callback dynamic variables and types from WhatsApp. 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.

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:

• "SMS send" for SMS channel
• "Email send" for the Email channel.
  The field is disabled when you select the default option.
• “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.io 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. Enter the URL Endpoint to trigger.
      2. In the Enter Endpoint field, enter the URL at which the callback information should be received.
      3. 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 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 Enter Endpoint field, enter the URL at which the callback information should be received.
      • 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.
      4. Enter the required headers as a key/value pair.
   2. POST: Use the POST method to send data to the server.
      1. Enter the URL Endpoint to trigger.
      2. Enter the required headers as a key/value pair.
      3. Provide the request body in any one of the four body types—XML, JSON, HTML, or Text.
         For example,

      https://webhook.site/93e95c0d-53eb-4960-b628-6a03cb672946,
      "body":{"name":"name",
      "phone":"<whatsapp_number>",
      "address":{"formatted_address":"<address.formatted_address>" }
      

      
      

7. 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 information on basic authentication, refer to Basic Authentication.
• Use the Headers field to indicate how the callback response should be presented using the “Content Type”.

8. Click the Enable Encryption toggle button. The fields related to encryption are displayed. This is an optional field.
   For more information on encryption, refer to: Callback Encryption.
9. Click Enable Callback Required Options toggle button.
   This option can be useful for chatbot services. This toggle is for internal purposes related to the chatbot and it is enabled/disabled as needed by Kaleyra personnel assisting the customer with chatbot creation.

📘

Note:

To know more about the callback advanced authentication feature, see Callback Advanced Authentication.

10. 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.
11. Click Save to save the callback profile in your kaleyra.io account.
    The saved profiles are listed on the Callback Profile page. You can filter the data on the listing page by using the Callback Profile Name, HTTP Method, and Created Date range for accurate results.

📘

Note:

Each Callback profile created has a unique ID (as shown in the following image) that you can add to your API call to receive updates about the specific resource. For example, a submitted SMS, using the configuration defined in the callback profile itself.

To copy the Callback profile ID, click the copy icon corresponding to the ID, this copies the ID to the clipboard.

Callback Reports

Kaleyra.io enables you to get automated Callback reports through mail. If you enable the Callback Report, then you get an email with the count of all failed and delivered callbacks with 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

To edit a callback profile:

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

The Callback Profiles page appears.

2. Click the three dots corresponding to the callback profile and click Edit.

The Edit Callback Profile page appears.

3. Edit the details as required and click Save.

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:

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

The Callback Profiles page appears.

2. Click the three dots corresponding to the callback profile and click Duplicate.

The Duplicate Callback Profile page appears.

3. Rename the callback profile.
4. Edit the details as required and click Save.

Delete a Callback Profile

To delete a callback profile:

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

The Callback Profiles page appears.

2. Click the three dots corresponding to the callback profile and click Delete.

The Confirmation popup appears.

3. Click Yes, Delete to delete the callback profile.

📘

Note:

A deleted callback profile cannot be restored.

A success message is displayed indicating that the callback profile has been deleted.

Re-trigger a Failed Request

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

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

The Callback Profiles page appears.

2. Click the three dots corresponding to the callback profile and click Re-trigger failed requests.

The Confirmation popup appears.

3. Click Retrigger to retrigger the callback profile.

📘

Note:

All stored failed callbacks sent using the information of the selected callback profiles will be sent again to the configured endpoint using the configuration of the selected callback profile.

A success message is displayed indicating that the callbacks are retriggered.

Disable a Callback Profile

To disable a callback profile:

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

The Callback Profiles page appears.

2. Click the three dots corresponding to the callback profile and click Disable.

The Confirmation popup appears.

3. Click Disable to disable the callback profile.

📘

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.

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

Enable a Callback Profile

Any disabled callback profile can be enabled and used again. To enable a callback profile:

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

The Callback Profiles page appears.

2. Click the three dots corresponding to the callback profile and click Enable.

The Confirmation popup appears.

3. Click Enable to enable the callback profile.

A success message is displayed indicating that the callback profile has been enabled.