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

API Request to List Message API

To list message API, use the /messages endpoints with the following request method:

Request Format

The following is the request format to list the message API through WhatsApp:

curl --location 'https://api.kaleyra.io//v1/<sid>/messages' \
--header 'api-key: <api_key>' \
--form 'to="<to_number>"' \
--form 'type="<message_type>"' \
--form 'channel="<channel_name>"' \
--form 'from="<from_number>"' \
--form 'body="<body_text>"' \
--form 'header="{ \"type\": \"text\",
    \"text\": \"<header_text>\"}"' \
--form 'footer="<footer_text>"' \
--form 'action="{
            \"button\": \"<button>\",
            \"sections\": [
                {
                    \"title\": \"<title>\",
                    \"rows\": [
                        {
                            \"id\": \"<id1>\",
                            \"title\": \"<title1>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id2>\",
                            \"title\": \"<title2>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id3>\",
                            \"title\": \"<title3>\",
                            \"description\": \"<description>\"
                        }
                    ]
                },
                {
                    \"title\": \"<title>\",
                    \"rows\": [
                        {
                            \"id\": \"<id4>\",
                            \"title\": \"<title4>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id5>\",
                            \"title\": \"<title5>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id6>\",
                            \"title\": \"<title6>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id7>\",
                            \"title\": \"<title7>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id8>\",
                            \"title\": \"<title8>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id9>\",
                            \"title\": \"<title9>\",
                            \"description\": \"<description>\"
                        },
                        {
                            \"id\": \"<id10>\",
                            \"title\": \"<title10>\",
                            \"description\": \"<description>\"
                        }
                    ]
                }
            ]
}"' \
--form 'callback_url="<callback_url>"'

Sample Request Format

The following is the sample request format to list message API through WhatsApp:

curl --location 'https://api.kaleyra.io//v1/HXXXXXXX071US/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'to="+91XXXXXXXXXX"' \
--form 'type="list"' \
--form 'channel="whatsapp"' \
--form 'from="+91XXXXXXXXXX"' \
--form 'body="Hi Welcome"' \
--form 'header="{ \"type\": \"text\",
    \"text\": \"This is the header content\"}"' \
--form 'footer="This is the footer content"' \
--form 'action="{
            \"button\": \"cta-button-content-here\",
            \"sections\": [
                {
                    \"title\": \"1st section\",
                    \"rows\": [
                        {
                            \"id\": \"1\",
                            \"title\": \"1st sec 1 Row\",
                            \"description\": \"Its Description-here 1st row\"
                        },
                        {
                            \"id\": \"2\",
                            \"title\": \"1st section 2 Row\",
                            \"description\": \"Its Description-here 2nd row\"
                        },
                        {
                            \"id\": \"3\",
                            \"title\": \"1st section 3 Row\",
                            \"description\": \"Its Description-here 3rd row\"
                        }
                    ]
                },
                {
                    \"title\": \"Second section\",
                    \"rows\": [
                        {
                            \"id\": \"4\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"Description-here\"
                        },
                        {
                            \"id\": \"5\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"2nd section 2nd row description\"
                        },
                        {
                            \"id\": \"6\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"2nd section 2nd row description\"
                        },
                        {
                            \"id\": \"7\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"2nd section 2nd row description\"
                        },
                        {
                            \"id\": \"8\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"2nd section 2nd row description\"
                        },
                        {
                            \"id\": \"9\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"2nd section 2nd row description\"
                        },
                        {
                            \"id\": \"10\",
                            \"title\": \"2nd section 1 Row\",
                            \"description\": \"2nd section 2nd row description\"
                        }
                    ]
                }
            ]
}"' \
--form 'callback_url="sample_26fb2aa3-d2eb-4799-9503-b1eabXXXX9fc"'

Parameters and Data Types

The following is the list of parameters and data types supported to list message API:

Parameter	Data Type	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	API key generated from kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	True
`to_number`	Integer	Specifies the to number to be sent.	+91XXXXXXXXXX	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.	list	True
`channel_name`	String	Specifies the channel name.	whatsapp	True
`from_number`	Integer	The WhatsApp business number registered with Kaleyra.io from which the message is to be sent.	+91XXXXXXXXXX	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.	Hi, Welcome.	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 the 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
`action`	Object	Specifies the action you want the user to perform after reading the message.	Action message.	True
`callback_profile`	String	Specifies the callback profile to receive notifications regarding the WhatsApp message status (sent, delivered, read, and failed). For more information related to callback profiles, see callback profiles page. Note: You can also use "callback URL" for the WhatsApp channel.	sample_26fb2aa3-d2eb-4799-9503-b1eabXXXX9fc	False

The following is the list of parameters and data types supported to list message API:

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

Sample Success Response

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": {}
}

Sample 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!"
    }
}

Updated about 1 month ago

List Message API

📘
Notes:

Base URL

📘
Note:

API Request to List Message API

Request Format

Sample Request Format

Parameters and Data Types

Response Format

Sample Success Response

Sample Failure Response

📘Notes:

Base URL

📘Note:

API Request to List Message API

Request Format

Sample Request Format

Parameters and Data Types

Response Format

Sample Success Response

Sample Failure Response

📘
Notes:

📘
Note: