Interactive messages: buttons, and the correlation problem nobody expects
Adding tappable buttons to a template sounds like a small UI upgrade. It quietly introduces a real backend problem — knowing which specific message a generic button tap was actually about — that most first attempts don't see coming.
6 min read
Two completely different things, easy to conflate
- Buttons attached to a template — defined when the template itself is created, rendered natively by WhatsApp under the message. WhatsApp handles detecting the tap; the receiving backend's job is only to receive the resulting webhook event.
- A free-text reply to any message — no button involved, arrives via the same webhook, a different payload shape.
Both need the inbound webhook receiver from the previous lesson already built and listening.
Button types — and one asymmetry that drives the whole design
| Button type | What it does | Webhook event on tap? | Per-send dynamic data? |
|---|---|---|---|
| Quick Reply | Tappable chip, sends back a fixed reply | Yes | No — payload is fixed at template-creation time, identical on every send |
| Phone Number (Call-to-Action) | Opens the dialer | No | No |
| URL (Call-to-Action) | Opens a link | No | Yes — one suffix appended to a base URL, set per send |
A URL button is the easy case: put whatever per-send identifier is needed directly in the link itself, exactly as it would already appear in the message body as plain text. A Quick Reply button is the hard case — tapping "Confirm" always sends back the literal same payload string, no matter which specific message, or which specific customer's booking, it was attached to. The tap alone can't tell you which thing it was about.
The correlation problem, and its actual fix
Every inbound webhook event for a button tap includes a context object pointing back at the specific message being replied to:
{
"messages": [{
"from": "15551234567",
"type": "button",
"button": { "text": "Cancel", "payload": "Cancel" },
"context": { "id": "wamid.ORIGINAL_MESSAGE_ID" }
}]
}context.id is the message ID (WAMID) Meta returned when the business sent the original message. The missing piece is almost never on Meta's side — it's that a send function returning a bare boolean throws away the one value needed to resolve a later reply. The fix: capture and store the WAMID, linked to whatever internal record the message was about (an appointment, an order), the moment the send succeeds.
This small correlation table is easy to skip early ("no one's asked for buttons yet") and becomes a hard requirement the moment buttons are added — worth building deliberately once buttons are on the roadmap, rather than retrofitting it under time pressure.
A payload assumption that costs real debugging time: it defaults to the button's own display text
Notice the payload above is "Cancel", not some arbitrary constant like CANCEL_APPOINTMENT. An unconfigured Quick Reply button's tap payload defaults to its own display text — not a developer-chosen string — unless the template-submission API is explicitly given a payload override. A button labeled "Cancel" sends back the literal string "Cancel"; the Arabic version of that same button, labeled "إلغاء", sends back "إلغاء" — a different string for a different language, for what is logically the same action.
The practical implication: a webhook handler that checks payload === "CANCEL_APPOINTMENT" and never sees that string, because no such string was ever configured, silently fails to match on every real tap — while everything else (the correlation lookup, the verification handshake) looks completely correct. The fix is either matching against the real per-language display text a template was actually submitted with, or checking whether the specific template-submission flow being used supports an explicit payload override before assuming either way. This is exactly the kind of mismatch that unit tests calling a handler function directly won't catch, because the test author supplies whatever payload they assumed would arrive — only a live tap against a real, submitted template surfaces it.
Payload shapes worth branching on
// Quick Reply button tap on a TEMPLATE (not the separate interactive-message API)
{ "type": "button", "button": { "payload": "Cancel" }, "context": { "id": "wamid..." } }
// Free-text reply
{ "type": "text", "text": { "body": "can I move it to 5pm?" }, "context": { "id": "wamid..." } }
// A reply to a *list* message (a different, separate interactive feature)
{ "type": "interactive", "interactive": { "type": "list_reply", "list_reply": { "id": "...", "title": "..." } } }Note the inconsistency worth remembering: a template's Quick Reply tap arrives as type: "button", not type: "interactive" — that second shape is reserved for the separate (non-template) interactive-messages API. Easy to mix up when reading documentation that covers both.
The 24-hour window applies here too
A button tap or a free-text reply is a customer-initiated message — it opens the same free-form window covered in the previous lesson. Confirming "Your appointment has been cancelled" back to the customer, in that window, is a plain text send, not another template.
A security note worth naming honestly
A button tap only proves "someone with access to this WhatsApp number tapped it" — not that it's genuinely the specific person the account belongs to. That's an acceptable trust model for read-only or low-stakes actions. It is not an acceptable trust model, on its own, for anything with real financial or account-modification stakes — a phone can be lost, borrowed, or spoofed. Extending this pattern to something higher-stakes needs a real authentication discussion first, not an assumption that "it came from the right number" is proof enough.
Unit tests aren't the finish line for this pattern
Everything in this lesson — the correlation table, the payload-defaulting behavior, the subscribed-app/publish-status requirements from the previous lesson — can be fully unit-tested and still fail the first time it meets real traffic, because building this crosses a genuine platform boundary (Meta's webhook delivery, account-level subscription and publish state) that no amount of mocking a request payload can substitute for. Budget for an actual live tap-and-confirm test against a real, submitted template before calling an interactive-message feature done — it's the only way several of the gotchas in this domain ever actually surface.
Further reading
Check your understanding
A quick comprehension check — not tracked, not graded, just for you.
1. A reminder template has a Quick Reply "Cancel" button. A hundred different customers each tap it. What does the webhook payload for each tap contain?
2. What field in an inbound button-tap webhook event points back to the specific message that was tapped?
3. A send function currently returns a plain boolean. What change is needed to support resolving Quick Reply button taps later?
4. A treasurer-style feature is proposed: a button tap that directly triggers a financial action (e.g. "waive this payment"). What does this lesson say about that?
5. A webhook handler checks for `payload === "CANCEL_APPOINTMENT"` on a template button labeled "Cancel", submitted without any explicit payload override. Real taps never match. Why?