WhatsApp Interactive Messages: Reply Buttons, Lists, and CTA URL Buttons
WhatsApp interactive messages API supports three message types, three different character-limit tables, and one shared rule that quietly breaks automated flows: none of them can be sent once the 24-hour customer service window has closed.
Reply Buttons
Up to 3 predefined replies attached to a message.
- Body text: up to 1,024 characters
- Footer text: up to 60 characters
- Button label: up to 20 characters, must be unique per message
- Button ID: up to 256 characters
- Optional header: text or media
- Tap fires a button_reply webhook (id + title)
List Messages
A single button that reveals a scrollable menu.
- Body text: up to 4,096 characters
- Footer text: up to 60 characters
- Button label: up to 20 characters, single button only
- Up to 10 sections, 10 rows total across all sections
- Section title & row title: up to 24 characters each
- Row description: up to 72 characters
- Tap fires a list_reply webhook (id + title + description)
CTA URL Buttons
A single button that opens an external link in the browser.
- Body text: up to 1,024 characters
- Footer text: up to 60 characters (required if used)
- Button label: up to 20 characters
- Only one URL button per message
- Header: text, image, video, or document
- Opens the link directly — not a WhatsApp reply
WhatsApp interactive messages API: the shared 24-hour session window
Reply buttons, list messages, and CTA URL buttons are all service messages under Meta’s customer service window rule. They can only be sent while that window is open — started by an inbound message or call from the user, and reset each time the user messages again. Once the window closes, only a pre-approved message template can go out, and template buttons follow their own, more limited component rules — they are not a drop-in replacement for the free-form interactive object.
Match the message type to the decision the user actually needs to make — a binary choice fits reply buttons, a multi-option menu fits a list, and sending someone to an external page fits a CTA URL button.
Design copy against the tightest limit in the flow, not the most generous one. A list message’s 24-character row title is the real ceiling, even though the same message body allows up to 4,096 characters.
Track the customer service window server-side so a scheduled or SaaS-triggered interactive message never fires after the window has silently closed.
Handle both button_reply and list_reply webhook shapes separately — list_reply carries an extra description field that button_reply does not.
Where automated flows break in practice
- A row or section title over 24 characters gets silently truncated on the client — it will not show up as an error in the API response.
- An interactive message sent after the customer service window has closed returns a delivery failure that looks like a token or permission problem, not a timing one.
- Row IDs that collide across sections change which payload a selection actually maps to on the webhook side.
- Chatbot and scheduler builders that reuse one body/footer string across all three types run into the CTA URL button’s stricter combined limits without noticing until send time.
Related reading: WhatsApp API approval and setup support, WhatsApp Cloud API webhook setup for the receiving side of these replies, and WhatsApp Flows API for structured multi-field forms beyond a simple list.
The official WhatsApp interactive messages API documentation describes reply buttons, list messages, CTA URL buttons, and their payload requirements.
Reply buttons work best for a small set of clear next actions, while list messages are better when a customer must choose from more options. CTA URL buttons should open a destination that matches the promise in the message.
A dependable WhatsApp interactive messages API integration validates payloads before sending and logs the response identifier for support and reconciliation.
Test WhatsApp interactive messages API templates with short labels, long labels, invalid URLs, expired sessions, and unexpected user replies.
Keep fallback text ready when the customer service window closes or a button payload is rejected.
Build the message composer around a typed payload model rather than assembling JSON strings in several code paths. Validate the action type, button identifier, display text, URL, and session state before the send call. This keeps WhatsApp interactive messages API changes reviewable and prevents accidental payload drift.
For observability, store the message identifier, conversation identifier, template or interactive type, and delivery status. When a customer taps a reply button, map the button identifier to a stable server-side action instead of trusting visible text.
Rate limits and retries also deserve explicit handling. Retry transient failures with a bounded policy, but do not resend a non-idempotent action simply because a network timeout hid the response. A clear audit trail makes chatbot behavior easier to explain.
Need Us to Get Your Meta App 100% Approved?
Stop losing weeks to repeated rejections. With 500+ apps approved, we handle your entire submission from start to finish. You get 100% Approval or a 100% Refund — and for your complete safety, you can hire us directly through Upwork or Fiverr Escrow (or use the WhatsApp / Calendar buttons in the header & footer).
Chat on WhatsApp