Mastering WhatsApp Interactive Messages: Quick Reply Buttons, List Messages & Location Requests
A comprehensive engineering guide to creating rich interactive components in Meta Cloud API v25.0 with real JSON payloads and webhook response schemas.
R&B Cloud Architecture Team
Senior API Architect · R&B Group
- Interactive messages provide structured UI elements (Buttons, Lists, Location Prompts) that eliminate customer typing errors and drive 3x faster conversions.
- Quick Reply buttons allow up to 3 action buttons per message with a 20-character text limit per button.
- List Messages can display up to 10 selectable items categorized across titled sections, perfect for product catalogs, service menus, and FAQs.
- Location Request messages trigger native device GPS sharing, allowing delivery and logistics apps to capture exact coordinates in one tap.
- Webhook responses for button and list selections arrive with explicit `reply.id` payloads, enabling clean `switch-case` state machine logic on your server.
Sending plain text messages on WhatsApp places the cognitive burden on your customer: they must manually type answers, numbers, or addresses, often resulting in spelling errors, confusion, and abandoned chats. Meta Cloud API v25.0 interactive messages solve this by providing native graphical UI elements—buttons, dropdown lists, and GPS location pickers—that customers can tap with a single thumb. In this technical manual, we break down the exact JSON schemas and webhook response parsers required to build high-converting interactive messaging experiences.
1. Quick Reply Buttons (type: "button")
Quick Reply buttons are the standard for micro-decisions: Yes/No confirmations, menu routing, or opting into an appointment. Meta supports up to 3 buttons per message.
Each button requires an `id` (an internal unique identifier) and a `title` (maximum 20 characters). When tapped, the customer’s WhatsApp sends an instant message displaying the title, and your webhook receives the unique button `id`.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "923001234567",
"type": "interactive",
"interactive": {
"type": "button",
"header": { "type": "text", "text": "Appointment Confirmation" },
"body": { "text": "Your site visit for Gulberg Heights is scheduled for tomorrow at 3:00 PM. Would you like to confirm?" },
"footer": { "text": "R&B Real Estate Solutions" },
"action": {
"buttons": [
{ "type": "reply", "reply": { "id": "btn_confirm_visit", "title": "Confirm Visit ✓" } },
{ "type": "reply", "reply": { "id": "btn_reschedule", "title": "Reschedule Time" } },
{ "type": "reply", "reply": { "id": "btn_cancel", "title": "Cancel Visit ✗" } }
]
}
}
}2. List Messages (type: "list")
When presenting more than 3 options, Quick Reply buttons cannot be used. List messages provide an elegant native modal drawer menu containing up to 10 rows grouped across multiple sections.
Each row contains an `id`, a `title` (max 24 characters), and an optional `description` (max 72 characters) providing extra context.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "923001234567",
"type": "interactive",
"interactive": {
"type": "list",
"header": { "type": "text", "text": "Explore Properties" },
"body": { "text": "Select your preferred development category to view available units:" },
"action": {
"button": "Browse Listings",
"sections": [
{
"title": "Gulberg Developments",
"rows": [
{ "id": "prop_g1", "title": "Executive 2-Bed Flat", "description": "1,450 sq ft · PKR 3.2 Crore" },
{ "id": "prop_g2", "title": "Penthouse Suite", "description": "3,200 sq ft · Private Terrace" }
]
},
{
"title": "DHA Phase 6 Developments",
"rows": [
{ "id": "prop_d1", "title": "1-Kanal Designer Villa", "description": "Corner Plot · Brand New" }
]
}
]
}
}
}3. Ingesting Interactive Webhook Callbacks in Node.js
When a customer taps an interactive button or list item, Meta pushes an incoming webhook payload with `type: "interactive"`. Here is how R&B CRM routes these events cleanly:
export function handleInteractiveMessage(messageObj: any) {
const interactive = messageObj.interactive;
if (interactive.type === 'button_reply') {
const buttonId = interactive.button_reply.id;
const buttonTitle = interactive.button_reply.title;
console.log(`User selected button: ${buttonId} (${buttonTitle})`);
switch (buttonId) {
case 'btn_confirm_visit':
// Update CRM status to Confirmed
return scheduleSiteVisit(messageObj.from);
case 'btn_reschedule':
return promptCalendarSlots(messageObj.from);
}
}
if (interactive.type === 'list_reply') {
const selectedRowId = interactive.list_reply.id;
console.log(`User selected list item: ${selectedRowId}`);
return dispatchPropertyBrochure(messageObj.from, selectedRowId);
}
}Frequently Asked Questions
Can interactive button and list messages be sent as marketing broadcasts?
Yes! When designing marketing message templates inside Meta WhatsApp Manager, you can add Quick Reply buttons or CTA buttons (e.g. Website URL or Phone Call) directly to the template.
What is the character limit for list row titles?
List row titles can have up to 24 characters, and row descriptions can have up to 72 characters.
Interconnected Architecture Guides & Next Reads
The Ultimate Guide to WhatsApp Business CRM & Automation in Pakistan (2026)
Why traditional email CRMs fail in Pakistan, and how official Meta Cloud API v25.0 transforms sales pipelines.
Click-to-WhatsApp (CTWA) Ad Attribution: Tracking Conversions with Meta CAPI v25.0
How to close the feedback loop between Facebook & Instagram ads and closed WhatsApp sales.
Building 24/7 Autonomous WhatsApp Sales Agents with Google Gemini 2.5 Flash
How sub-second LLM reasoning automates real estate lead qualification and customer support.
Ready to Upgrade Your WhatsApp Sales System?
Launch official Meta Cloud API v25.0, autonomous Gemini 2.5 Flash lead qualification, and CAPI marketing attribution with R&B CRM. Start with a $0 card-backed 7-day trial.