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:

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

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

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
CONTENT_TYPEAlphanumericIndicates the format of the content the API will be processing.application/JSONTrue
API_KEYStringYour API Key generated by Kaleyra.io.
Refer to the Creating An API Key and Security Identifier document for steps to create API Key.
Ac4XXXXX21fTrue
TO_NUMBERIntegerSpecifies the to number to be sent.+1202XXXXXXXTrue
MESSAGE_TYPEStringFormat 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 templateTrue
CHANNEL_NAMEStringSpecifies the channel name.whatsappTrue
FROM_NUMBERIntegerThe WhatsApp business number registered with Kaleyra.io from which the message is to be sent.+1202XXXXXXXTrue
HEADER_TEXTStringOptional.
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_TEXTStringOptional.
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_TEXTStringOptional 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
ACTIONObjectSpecifies 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
NameDescription
typeThe 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.
textRequired if the type is set to text.

Specify the text for the header. Formatting allows emojis, but not markdown.
videoRequired if the type is set to video. Contains the media object for this video.
imageRequired if the type is set to image. Contains the media object for this image.
documentRequired if the type is set to document. Contains the media object for this document.
The body Object
NameDescription
textSpecifies 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
NameDescription
textRequired 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
NameDescription
buttonSpecifies 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.
sectionsAn 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 CodeDescription
'E413'Invalid/incorrect inputs.

Facebook Documentation