List Messages
How to send an interactive list message on the WhatsApp Cloud API — a menu with sections and up to 10 selectable rows.
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#
| Rule | Detail |
|---|---|
| Max rows total | 10 across all sections |
| Max sections | No hard limit, but keep it practical |
action.button | The label on the button that opens the list (max 20 chars) |
| Row title max | 24 characters |
| Row description max | 72 characters |
| Header | Optional — text only (no image) |
| Footer | Optional |
Frequently asked#
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#
Was this page helpful?
Still stuck? Open a support ticket and our team will help.