List Message API
POST Method
This List Message API is used to send List options (type - Interactive) to end-users in session messages through API. Also, you can offer a simple and more consistent way for users to make a selection when interacting with a business.
You can send the following details in an interactive object.
- Header (text)
- Body (message content)
- Footer (text)
- Action - Button for List messages (With button text)
- Section
a) Optional Section Header
b) Row (Each row has an ID, Title, and Description)
Notes:
- There must be at least one section object (maximum limit is set to ten section objects per API).
- You must add at least one rows object inside the section.
Base URL
<https://api.kaleyra.io/v1/><SID>
To list message API, perform the following steps:
- Signup or Login to Kaleyra.io and create your API key.
Before you get started, sign up for a Kaleyra.io account for free and Create an API Key. To view the API Key and the SID, see View API Key and SID.
Note:
After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in Kaleyra.io.
- API command for List Message API
Request Format - POST
To list message API, use the /messages endpoints.
curl --location --request POST 'https://api.kaleyra.io/v1/<SID>/messages'
--header 'Content-Type: <CONTENT_TYPE>'
--header 'api-key:<API_KEY>'
--form 'to=<TO_NUMBER>'
--form 'type=<MESSAGE_TYPE>'
--form 'channel=<CHANNEL_NAME>'
--form 'from=<FROM_NUMBER>'
--form 'header="{ \"type\": \"text\",
\"text\": \<HEADER_TEXT>\"}",
--form 'footer= <FOOTER_TEXT>",
--form 'body= <BODY_TEXT>",
--form 'action="{
"button": "cta-button-content-here",
"sections": [
{
"title": "your-section-title-content-here",
"rows": [
{
"id": "unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here"
}
]
},
{
"title": "your-section-title-content-here",
"rows": [
{
"id": "unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here"
}
]
}
]
}
Parameters and Variables
The following table displays the parameter and variables used:
| Parameter | Variable | Description | Example | Mandatory |
|---|---|---|---|---|
SID | String | Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key. | HXXXXXXX071US | True |
CONTENT_TYPE | Alphanumeric | Indicates the format of the content the API will be processing. | application/JSON | True |
API_KEY | String | Your API Key generated by Kaleyra.io. Refer to the Creating An API Key and Security Identifier document for steps to create API Key. | Ac4XXXXX21f | True |
TO_NUMBER | Integer | Specifies the to number to be sent. | +1202XXXXXXX | True |
MESSAGE_TYPE | String | Format of the message that is to be sent. For more details on the supported formats, refer to the Messaging on WhatsApp Business document. | text, list, reply and template | True |
CHANNEL_NAME | String | Specifies the channel name. | True | |
FROM_NUMBER | Integer | The WhatsApp business number registered with Kaleyra.io from which the message is to be sent. | +1202XXXXXXX | True |
HEADER_TEXT | String | Optional. If you decide to include the header text, you must set the header’s type to text and add a text field with the desired content. | This is header content. | True |
FOOTER_TEXT | String | Optional. The footer of the message. Emojis and markdown are supported. The maximum length is set to 60 characters. | This is the footer content. | True |
BODY_TEXT | String | Optional for type product. Required for other message types. The body of the message. Emojis and markdown are supported. The maximum length is set to 1024 characters. | This is the text message content. | Tru |
ACTION | Object | Specifies the action you want the user to perform after reading the message. | Action message. | True |
Interactive Object
The interactive object generally contains 4 main components: **header**, **body**, **footer**, and **action**. Additionally, some of those components can contain one or more different objects:Inside the header, you can nest media objects.
Inside action, you can nest section and button objects.
The header Object
| Name | Description |
|---|---|
| type | The header type you would like to use. Supported values are: • text: Used for List Messages, Reply Buttons, and Multi-Product Messages. • video: Used for Reply Buttons and Multi-Product Messages. • image: Used for Reply Buttons and Multi-Product Messages. • document: Used for Reply Buttons and Multi-Product Messages. |
| text | Required if the type is set to text. Specify the text for the header. Formatting allows emojis, but not markdown. |
| video | Required if the type is set to video. Contains the media object for this video. |
| image | Required if the type is set to image. Contains the media object for this image. |
| document | Required if the type is set to document. Contains the media object for this document. |
The body Object
| Name | Description |
|---|---|
| text | Specifies the body content of the message. Emojis and markdown are supported. Links are supported. The maximum length is set to 1024 characters. |
The footer Object
| Name | Description |
|---|---|
| text | Required if the footer object is present. Specify the footer content. Emojis and markdown are supported. Links are supported. The maximum length is set to 60 characters. |
The action Object
| Name | Description |
|---|---|
| button | Specifies the button content. It cannot be an empty string and must be unique within the message. Do not allow emojis or markdown. The maximum length is set to 20 characters. |
| sections | An array of section objects. Minimum of 1 and a maximum of 10. |
Response Format
Success Format
This section provides you with the successful JSON response format.
{
"id": "XXXXXXXXX-XXXX-4e6e-a52f-9bXXXXXX3888",
"type": "list",
"body": "This is the test message",
"createdDateTime": "2021-11-09 04:20:23+00:00",
"totalCount": 1,
"data": [
{
"message_id": "XXXXXXX6-6d90-4e6e-a52f-9bXXXXXXXXXX:0",
"recipient": "XXXXXXXX9189"
}
],
"error": {}
}
Failure Response
{
"code": "E413",
"message": "Invalid/incorrect inputs",
"data": [],
"error": {
"action": "For the type list, action field is mandatory and cannot be empty!",
"body": "For the type list, body field is mandatory and cannot be empty!"
}
}
{
"code": "E413",
"message": "Invalid/incorrect inputs",
"data": [],
"error": {
"action": "For the type list, action field is mandatory and cannot be empty!"
}
}
Sample Request
curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'api-key: A8eXXXXXXXXXX9b05581a2182XXXX1d17'
--form 'to="+1202XXXXX900,+1202XXXXXXXX"'
--form 'type="list"'
--form 'channel="WhatsApp"'
--form 'from="+1202XXXXXXX"'
--form 'header="{ \"type\": \"text\",
\"text\": \"This is header content\"}"'
--form 'footer="Hey footer"'
--form 'action="{
"button": "cta-button-content-here",
"sections": [
{
"title": "your-section-title-content-here",
"rows": [
{
"id": "unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here"
}
]
},
{
"title": "your-section-title-content-here",
"rows": [
{
"id": "unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here"
}
]
}
]
}
Error Codes
The following table provides information about the error codes you would receive when executing the List Message API.
| Error Code | Description |
|---|---|
| 'E413' | Invalid/incorrect inputs. |
Facebook Documentation
developers.facebook.comUpdated 11 months ago