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.

Base URL

<https://api.kaleyra.io>

To create a callback profile, perform the following steps:

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 '<url>/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":""}	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 as application/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.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.

Updated 4 months ago