Skip to main content
A list message presents the recipient with a button that opens a scrollable menu of options grouped into sections. Each option (row) has an ID, title, and optional description. When the customer selects a row, its ID is sent back to your webhook. Use this when you have 4–10 options — more than reply buttons (max 3) can handle.

​
Sending a list message

{
  "messaging_product": "whatsapp",
  "to": "919959623255",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Our Services" },
    "body": { "text": "Please select a service from the list below." },
    "footer": { "text": "Tap to choose" },
    "action": {
      "button": "View Options",
      "sections": [
        {
          "title": "Support",
          "rows": [
            { "id": "row_billing", "title": "Billing issue", "description": "Help with payments and invoices" },
            { "id": "row_technical", "title": "Technical support", "description": "App or account problems" }
          ]
        },
        {
          "title": "Sales",
          "rows": [
            { "id": "row_new_order", "title": "Place new order", "description": "Browse and buy products" }
          ]
        }
      ]
    }
  }
}

​
Rules

RuleDetail
Max rows total10 across all sections
Max sectionsNo hard limit, but keep it practical
action.buttonThe label on the button that opens the list (max 20 chars)
Row title max24 characters
Row description max72 characters
HeaderOptional — text only (no image)
FooterOptional

​
Frequently asked

Use type: "interactive" with interactive.type: "list". Define action.sections with rows — each row has an id and title. When the customer taps a row, the id is sent to your webhook.
Reply buttons show up to 3 buttons directly in the chat. List messages show a button that opens a scrollable menu with up to 10 options grouped in sections. Use buttons for simple yes/no; use lists for menus with many options.
WhatsApp sends the row’s id back to your webhook as an inbound interactive message. Your server reads the id to route the customer.
No. List message headers support text only — not images.

​
Gotchas & common mistakes

  • Over 10 rows — the API rejects the request. Keep the total rows across all sections at 10 or fewer.
  • action.button missing — this is the label for the button that opens the list. Required, max 20 characters.
  • Row title too long — max 24 characters.
  • Image header — list messages only support "type": "text" in the header. Unlike reply buttons, you cannot use an image header here.