Create Callback Profiles

POST Method

Kaleyra.io offers an API that enables you to create callback profiles. You can configure the attributes to be received through the callback associated with the callback profile while creating it.

To create a callback profile, perform the following steps:

Base URL

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

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

API request to create callback profiles

To create a callback profile, use the /callback/profiles endpoint with the following request method:

Request Format

curl --location --request POST 'https://<api_domain>/v1/<sid>/callback/profiles' \
--header 'api-key: <api-key>' \
--header 'Content-Type: <content-type>' \
--data-raw '{
    "title": "<title>", 
    "http_method": "<http_method>",
    "url": "<url>",
    "body": "<body>",
    "response_message": "<response_message>",
    "headers": "<headers>",
    "enc": "<enc>",
    "channel":"<channel>",
    "events": "<events>"
}'

The following table describes the parameter used for creating a callback profile:

Parameter

Data Type

Description

Example

Mandatory

sid

String

Account SID (Security Identifier).

HXXXXXXX071IN

Yes

content-type

String

The format in which the data is sent.

application/json

Yes

api-key

String

API key generated from Kaleyra.io account.

Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3

Yes

title

String/Characters

The Callback Profile name.

  • *Note**: It should respect the following conditions:
  • Minimum three characters.
  • Only alphabet, numbers, spaces, hyphens, and underscores are allowed.

Callback_Profile_Test_1

Yes

http_method

String

The method type you want to use for the Callback Profile that you are creating.
Allowed HTTP Methods are:

  • GET
  • POST
  • PUT
  • DELETE

POST

Yes

url

String

The endpoint on which you want to receive a callback. It could be HTTP or HTTPS.

https://webhook.site/dxxxxxx9-bxx8-4xx2-9xx5-4xxxxxxxxxx8

Yes

body

Object

For POST and PUT methods, you need to provide the callback body. It should be in JSON format.

The body is defined by the callback profile creator. For example, the callback profile created for the Default - No Channel Selected, Dynamic Variable is not defined by default, it has to configure based on the requirements.

{"name":"<name>"}

Yes

response_message

String

The message you want to send to a requester when the Payload is successful.
It is specific to chatbots and can be used only with chatbots. It may contain replacers.

For example, when a request is made for Chatbot and if the payload is successful then you can update the message like, Thank you, {"name": "first_name"} and in response, it will be:
Thank you, John, according to the database.

Thank you, {"name": "John"}

No

headers

Object

Add additional headers and corresponding values that will be added to the HTTP/HTTPS request sent to your configured endpoint when using this callback profile.

When a header is not specified as multipart/form-data, then by default it will consider the content-type asapplication/json and in the response, the user will not see the data in Form value instead of that they will view in JSON format.

{  
      "key1": "value1",  
      "key2":"value2"  
      }

No

enc

Object

Encryption Parameters must be specified when you want to encrypt callback parameters. Encrypt the callback data by using specified algorithms, keys, and IV details. Apart from these three mandatory parameters, you have Params which is an optional parameter. For more information, see Callback Encryption.

"enc": {  
      "algo": "AES-128-GCM",  
      "key": "1xxxxxxxxxxxxxx4", //16-bit long key  
      "IV": "3xxxxxxxxxxxxxx4" //16-bit long key  
      }

No

channel

String

Specify for which channel the callback profile is created. Possible value is "sms" or "Defatul - No Channel Selected". Default - No Channel Selected, can be used for creating a profile to be used for getting information related to any channels other than SMS, like WhatsApp, Email, and so on.

sms

No

events

Array

The event you want to add to the channel. When you create a callback profile for Default - No Channel Selected then it does not require events. You can put null for events, except for SMS. For SMS it is SMS-sent.

SMS-sent

No

Sample Request

The following is the sample request:

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXXXXXXX071IN/callback/profiles' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
 "title": "Callback_Profile_Test_1",
 "http_method": "PUT",
 "url": "https://webhook.site/aexxxxb3-axx4-4xx9-8xxc-efxxxxxxxx35",
  "enc": {
    "algo": "AES-128-GCM",
    "key": "12xxxxxxxxxxxx34",
    "IV": "12xxxxxxxxxxxx38"
  },
  "headers": {
    "x-api-key": "A-RANDOM-API-KEY"
  },
  "body": {
    "name": "John Doe"
  },
  "response_message": "Expected response message",
    "channel":"sms",
    "events": "SMS-sent"
}'

Sample Success Response

The following are the sample success response for callback profile creation:

{
    "code": "RBC024",
    "message": "Profile created successfully",
    "data": {
        "title": "some title",
        "http_method": "POST",
        "url": "https://webhook.site/dxxxxxx9-bxx8-4xx2-9xx5-4xxxxxxxxxx8",
        "body": {
            "key": "value"
        },
        "enc": {
            "algo": "AES-128-CFB",
            "key": "K1xxxxxxxxxxxx2P",
            "IV": "POxxxxxxxxxxxxLY" //16-bit key either number or alphabets format>
        },
        "headers": "{\"aa\":\"heyy\"}", 
        "replacers": {
            "key": "value"
        }, // {"<replacer>": "value"}
        "response_message": "string",
        "events": "[\"\"]", //  "[\"event1\",\"event2\"]"
        "profile_id": "stage_.....",
        "status": 1, //1 - active; 2 - Auto-Disabled ; 3 - Disabled;  
    },
    "error": {},
    "status": 201
}

Sample Failure Response

The following is a sample failure response:

{
    "code": "RBC302",
    "message": "body must have required property 'title'",
    "data": {},
    "error": [
        {
            "body": "body must have required property 'title'"
        }
    ],
    "status": 400
}

For more information about response codes and statuses for creating a callback profile, see Response Codes and Statuses for Creating Callback Profile.





© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.