Browse guides

List Messages

How to send an interactive list message on the WhatsApp Cloud API — a menu with sections and up to 10 selectable rows.

On this page

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#

json
{
  "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#

How do I send a menu or list of options on WhatsApp?

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.

What is the difference between list messages and reply buttons?

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.

What happens when the customer selects a row?

WhatsApp sends the row's id back to your webhook as an inbound interactive message. Your server reads the id to route the customer.

Can I put images in a list message?

No. List message headers support text only — not images.

Gotchas & common mistakes#

Still stuck? Open a support ticket and our team will help.