List message

Note:

Currently, list messages are only supported by the WhatsApp channel. List messages are not natively supported on channels other than WhatsApp, and they may not be transcoded into text on other channels.

A list message is an interactive message. There are two types of list messages:

Choice list messages provide the recipient with a list of up to 10 choices. Pressing one of the choices causes a response to be sent back in a callback. Product list messages provide the recipient with a list of products (or a singular product) in a product catalog. Pressing one of the products allows the user to add the product to their cart.

Note:

Choice list messages and product list messages share some of the same schema structure. However, at the items level, you must specify either choice or product. Subsequent schema levels are specific to the type of message you specified.

Choice list message

You can send a choice list message by making a POST request to the /messages:send Conversation API endpoint with the following payloads:

{
  • "app_id": "{{APP_ID}}",
  • "recipient": {
    • "contact_id": "{{CONTACT}}"
    },
  • "message": {
    • "list_message": {
      }
    }
}

Product list message

You can send a product list message by making a POST request to the /messages:send Conversation API endpoint. However, you must have a corresponding catalog that contains approved items. Then, you'll be able to use the catalog and product IDs to send list product messages. The following payload is only a structural example, and the details should not be used in an actual API call:

{
  • "app_id": "{{APP_ID}}",
  • "recipient": {
    • "contact_id": "{{CONTACT}}"
    },
  • "message": {
    • "list_message": {
      }
    }
}

List message schema

A list message can take the following parameters and properties. Required parameters are marked.

title
required
string

A title for the message that is displayed near the products or choices.

required
Array of objects (List Section)

List of ListSection objects containing choices to be presented in the list message.

description
string

This is an optional field, containing a description for the message.

object

Additional properties for the message. Required if sending a product list message.

The following sections give examples of how list messages are rendered in each channel and specific parameter support:

WhatsApp

WhatsApp channel natively supports list messages. The following images give examples of the different list message functionalities:

Choice list message

List Message

Choice list message details

List Message

Product list message (single product)

Single Product Message

Product list message details (single product)

Single Product Message Details

Product list message (multi-product)

Multi Product Message

Product list message details (multi-product)

Multi Product Message Details

Was this page helpful?