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)

📘

Note:

  • 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/

To list message API, perform the following steps:

1. 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.

📘

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.

2. 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.

whatsapp

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


Did this page help you?