List message
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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
Product 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": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "list_message": {
      "title": "Choose your icecream flavor",
      "description": "The best icecream in town!",
      "sections": [
        {
          "title": "Fruit flavors",
          "items": [
            {
              "choice": {
                "title": "Strawberry",
                "postback_data": "Strawberry postback"
              }
            },
            {
              "choice": {
                "title": "Blueberry",
                "postback_data": "Blueberry postback"
              }
            }
          ]
        },
        {
          "title": "Other flavors",
          "items": [
            {
              "choice": {
                "title": "Chocolate",
                "postback_data": "Chocolate postback"
              }
            },
            {
              "choice": {
                "title": "Vanilla",
                "postback_data": "Vanilla postback"
              }
            }
          ]
        }
      ],
      "message_properties": {
        "menu": "Menu text",
        "whatsapp_header": "WhatsApp header text"
      }
    }
  }
}

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": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{CHANNEL}",
          "identity": "{IDENTITY}"
        }
      ]
    }
  },
  "message": {
    "list_message": {
      "title": "Title for the list message with products",
      "description": "Description (or subtitle) for list message with products",
      "sections": [
        {
          "title": "Facebook product catalog item set name",
          "items": [
            {
              "product": {
                "id": "product_1_id",
                "marketplace": "FACEBOOK"
              }
            },
            {
              "product": {
                "id": "product_2_id",
                "marketplace": "FACEBOOK"
              }
            }
          ]
        }
      ],
      "message_properties": {
        "catalog_id": "id_of_catalog"
      }
    }
  }
}

List message schema

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

list_messageobject(List Message)

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

WhatsApp channel natively supports list messages. Note the following limitations:

The top-level title property supports a maximum of 1024 characters
The top-level description property supports a maximum of 60 characters
The menu property of the message_properties parameter supports a maximum of 20 characters
The whatsapp_header property of the message_properties parameter supports a maximum of 60 characters and this property is only supported for choice list messages
The title property of the sections object supports a maximum of 24 characters
The title property of a choice object supports a maximum of 24 characters
The description property of a choice object supports a maximum of 27 characters
The postback_data property of a choice object supports a maximum of 200 characters