Ricevere le risposte interattive WhatsApp

Un tocco su un pulsante di risposta, una riga di lista o il pulsante quick-reply di un template arriva come messaggio in entrata a sé stante con interactive_reply. Il ramo ti restituisce l'handle che hai impostato all'invio, così un flusso si ramifica sul tuo identificatore anziché sull'etichetta che il contatto ha visto.

Cosa contiene una risposta interattiva in entrata

type indica il tipo di tocco, e il campo con lo stesso nome lo contiene:

Esempio di codice

{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive_reply": {
    "type": "button",
    "button": { "slug": "cancel-booking", "text": "Cancel" }
  },
  "created_at": "2026-08-25T09:04:11Z"
}

type	Campo	Cosa contiene
button	button	slug e text di un pulsante di risposta o del pulsante quick-reply di un template
list	list	slug e text della riga scelta dal contatto, più la sua description quando presente

Una riga di lista sostituisce button con list e aggiunge la seconda riga mostrata:

Esempio di codice

{
  "interactive_reply": {
    "type": "list",
    "list": {
      "slug": "priority_express",
      "text": "Priority Mail Express",
      "description": "Next day to 2 days"
    }
  }
}

slug è l'handle che hai dichiarato e che il contatto non ha mai visto; text è l'etichetta che ha letto. Ramifica su slug. Le etichette vengono riformulate e tradotte, e in un tocco sul pulsante quick-reply di un template il slug è il payload dichiarato dal template, che WhatsApp imposta sull'etichetta del pulsante stesso.

La lista dei tipi è aperta: WhatsApp aggiunge tipi interattivi nel tempo, quindi tratta un type che non riconosci come un tipo futuro anziché come un errore, e registra il messaggio nel log invece di interrompere la lettura.

Collegare un tocco a ciò che hai inviato

in_reply_to_message_id indica il messaggio che conteneva il pulsante o il menu, ed è così che sai a quale domanda appartiene questa risposta. WhatsApp non lo riporta a ogni tocco, e la risoluzione può anche fallire: in quel caso il campo viene omesso, non riportato vuoto. La sezione risposte citate dell'hub spiega cosa significa un fallimento e per quanto tempo un messaggio citato resta risolvibile.

Dove la correlazione deve essere affidabile, inserisci un tuo riferimento nel slug stesso, oppure in metadata all'invio, anziché dipendere dal campo. Vedi citare un messaggio per il lato invio.

I due tocchi che arrivano altrove

Due tipi interattivi rispondono senza alcun interactive_reply:

Una richiesta di posizione torna come una normale posizione in entrata.
Una richiesta di informazioni di contatto torna come schede contatto, con origin impostato su contact_request.

Un pulsante link non invia nulla indietro: il contatto esce verso l'URL e nessun messaggio in entrata registra il tocco. Un'integrazione che osserva solo interactive_reply perde tutti e tre.

Il payload del webhook

whatsapp.received contiene il ramo interactive_reply nell'envelope dell'evento, così un bot può rispondere a un tocco senza rileggere il messaggio:

Esempio di codice

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
    "to": { "phone_number": "+13124495569" },
    "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "interactive_reply": {
      "type": "button",
      "button": { "slug": "cancel-booking", "text": "Cancel" }
    },
    "tags": null,
    "metadata": null
  }
}

Aspetti da tenere d'occhio

interactive e interactive_reply sono direzioni opposte. interactive è ciò che hai inviato e non arriva mai in entrata; interactive_reply è ciò che il contatto ha toccato e non compare mai in un messaggio in uscita.
Un tocco riapre la finestra di servizio. È un messaggio in entrata, quindi riapre 24 ore di risposte libere allo stesso modo di un messaggio di testo.
Un contatto può toccare lo stesso pulsante due volte. Nulla deduplica i tocchi, quindi ciascuno è un messaggio a sé con il proprio ID. Rendi idempotente l'azione che esegui su un slug.
Un tocco su un vecchio menu arriva comunque. Un contatto che scorre indietro può toccare un pulsante di giorni fa, quindi verifica che il flusso sia ancora aperto anziché dare per scontato che il tocco risponda al tuo ultimo messaggio.

Passaggi successivi

Come funziona la ricezione: l'envelope in entrata, il recupero dei media e il webhook whatsapp.received
Messaggi interattivi WhatsApp: i sei tipi su cui un destinatario può toccare
Pulsanti di risposta WhatsApp: il lato invio di un tocco su pulsante
Menu a lista WhatsApp: il lato invio della scelta di una riga

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione