# Messaggi interattivi WhatsApp Un messaggio interattivo è testo più un elemento che il destinatario può toccare: un pulsante WhatsApp, un menu, un link, una card o una richiesta di posizione o dati di contatto. Dove una risposta a un template richiede di analizzare testo libero, un menu WhatsApp o un set di pulsanti WhatsApp offre al destinatario un insieme fisso di scelte e restituisce a te un valore che hai definito. Questa pagina copre ciò che i sei tipi hanno in comune; la pagina di ciascun tipo descrive la sua struttura e i suoi limiti specifici. ## I sei tipi | Tipo | Bird `interactive.type` | Header | Footer | Body max | | ---------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------ | ------ | ---------------------------- | | [Pulsanti di risposta](/docs/guides/whatsapp/message-types/interactive/reply-buttons) | `button` | testo, immagine, video, documento | sì | 1024 | | [Menu a lista](/docs/guides/whatsapp/message-types/interactive/list-menus) | `list` | solo testo | sì | 4096 | | [Pulsanti con link](/docs/guides/whatsapp/message-types/interactive/cta-url-buttons) | `cta_url` | testo, immagine, video, documento | sì | 1024 | | [Caroselli multimediali](/docs/guides/whatsapp/message-types/interactive/carousels) | `carousel` | nessuno sul messaggio; immagine o video per card | no | 1024 messaggio, 160 per card | | [Richieste di posizione](/docs/guides/whatsapp/message-types/interactive/location-requests) | `location_request_message` | nessuno | no | 1024 | | [Richieste di contatto](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) | `request_contact_info` | nessuno | no | 1024 | Ogni tipo è free-form: inviabile solo all'interno di una finestra di assistenza clienti aperta, e mai soggetto a revisione da parte di Meta come accade per un template. I messaggi interattivi sono contenuto free-form, quindi si applica la regola della finestra di assistenza clienti: consulta [la finestra di assistenza clienti](/docs/guides/whatsapp/message-types#the-customer-service-window) per capire cosa significa e cosa restituisce una finestra chiusa. Ogni invio interattivo richiede anche `from`, un numero di proprietà del tuo spazio di lavoro. I numeri gestiti da Bird non lo supportano, quindi un invio interattivo richiede prima di tutto un numero tuo collegato. ## Il campo di contenuto interattivo `interactive` è uno dei campi di contenuto mutuamente esclusivi su `POST /v1/whatsapp/messages`, accanto a `template`, `text`, `image` e gli altri: esattamente uno può essere presente in un invio. All'interno di `interactive`, `type` indica quale delle sei varianti è, e il campo specifico di quella variante contiene il resto (`buttons`, `list`, `cta_url` o `cards`). Lo schema esclude il campo di ogni altra variante, quindi combinare due varianti in un singolo invio genera un errore di validazione prima di raggiungere un handler. Per la request envelope, il modello di risposta `202` e i retry sicuri, consulta [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp) anziché ripeterli in questa pagina. Ecco un messaggio interattivo minimale: due pulsanti WhatsApp su un invio reply-buttons, una lingua alla volta. **TypeScript** ```typescript const msg = await bird.whatsapp.send({ to: "+15551234567", from: "+13124495648", interactive: { type: "button", body_text: "Your gardening workshop is scheduled for 9am tomorrow.", buttons: [ { type: "quick_reply", quick_reply: { slug: "change-booking", text: "Change" } }, { type: "quick_reply", quick_reply: { slug: "cancel-booking", text: "Cancel" } }, ], }, }); console.log(msg.id, msg.status); ``` Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/interactive.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/interactive.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/interactive.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/interactive.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/interactive.cli.md) · [MCP](/it-it/documentazione/guides/whatsapp/message-types/interactive.mcp.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/interactive.curl.md) ## Pulsanti Quattro dei sei tipi inseriscono un pulsante, e tutti si basano sulla stessa struttura: un oggetto discriminato il cui `type` è `quick_reply` o `cta_url`, ciascuno con il proprio campo annidato dello stesso nome. Un pulsante `quick_reply` contiene `slug` e `text`; un pulsante `cta_url` contiene `text` e `url`. Quali tipi accettano quale forma di pulsante: - I **pulsanti di risposta** inviano solo pulsanti `quick_reply`, da 1 a 3. - I **pulsanti con link** inviano esattamente un pulsante `cta_url`. - I **caroselli multimediali** inseriscono pulsanti in ogni card: un pulsante `cta_url` oppure fino a tre pulsanti `quick_reply`, e ogni card nel carosello deve concordare. - I **menu a lista** usano righe all'interno di sezioni anziché questo oggetto pulsante, trattate nella loro pagina dedicata. Il campo `slug` di un pulsante `quick_reply` è il tuo handle per quel pulsante. Non viene mai mostrato al destinatario, che vede solo la label `text`, e il `slug` viene restituito verbatim nella risposta. Questo ciclo è ciò che rende una risposta correlabile al pulsante che l'ha generata, quindi vale la pena dirlo una volta qui anziché in ogni pagina specifica. ## Leggere una risposta Premere un pulsante o scegliere una riga del menu invia un proprio messaggio in entrata, contenente un oggetto `interactive_reply`. `interactive_reply.type` è `button` o `list`; in entrambi i casi l'oggetto annidato contiene il `slug` e il `text` che hai dichiarato, cioè la label toccata che il destinatario ha effettivamente visto. I due tipi di richiesta, richieste di posizione e richieste di contatto, rispondono diversamente: la risposta a una richiesta di posizione è un normale messaggio in entrata di tipo [location](/docs/guides/whatsapp/message-types/interactive/location-requests), e la risposta a una richiesta di contatto è una [scheda contatto](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) in entrata, non un `interactive_reply`. Una risposta ti arriva attraverso la lista messaggi e `GET /v1/whatsapp/messages/{id}`, allo stesso modo di qualsiasi messaggio WhatsApp in entrata. Per agire su una risposta appena arriva invece di fare polling, iscriviti al webhook `whatsapp.received`: il suo payload contiene `interactive_reply`, quindi indica già il pulsante o la riga toccata. [Ricezione delle risposte interattive](/docs/guides/whatsapp/receiving-whatsapp/interactive-replies) descrive la struttura in lettura di un tap, il payload del webhook e i tap che arrivano su un altro campo. ## Citare un messaggio per correlare una risposta `in_reply_to_message_id` in un invio cita un messaggio precedente della stessa conversazione, e ogni messaggio, inviato o ricevuto, lo restituisce in lettura. È un unico campo per entrambe le direzioni. La correlazione che ottieni è asimmetrica. Un tap su un pulsante WhatsApp o una riga del menu porta il `context` di Meta, quindi `in_reply_to_message_id` si risolve nel messaggio che lo ha offerto. Una scheda contatto condivisa non porta alcun `context`, quindi non si risolve in nulla: correli la risposta a una richiesta di contatto tramite `from` e il timing, non tramite questo campo. La risoluzione passa attraverso un message-context store, e un miss **omette** il campo invece di riportarne uno. Sul wire è indistinguibile da una risposta che non risponde a nulla. Un'integrazione che richiede correlazione affidabile non dovrebbe basarsi solo su questo campo: porta il tuo `metadata` nell'invio e fai il match su quello. La finestra in cui un messaggio resta citabile è limitata a 15 giorni; oltre, l'invio fallisce con un `404` [`E15071`](/docs/api/errors/E15071), perché Bird non contiene più il provider id necessario per la citazione. [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp#quoting-a-message) gestisce il campo lato invio: la sua lunghezza, la sua risoluzione e la struttura della richiesta. ## Errori Tre codici di errore sono specifici del contenuto interattivo. Ciascuno si attiva solo sui tipi che hanno il campo controllato, quindi la quarta colonna indica quali tipi possono effettivamente generarlo. | Codice | Status | Cosa lo genera | Si applica a | | ------------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [E15055 `WhatsAppInteractiveLimitExceeded`](/docs/api/errors/E15055) | 422 | Il messaggio supera un limite per il suo tipo; attualmente, più di 10 righe nelle sezioni di una lista. | Solo menu a lista | | [E15056 `WhatsAppInteractiveDuplicateLabel`](/docs/api/errors/E15056) | 422 | Due pulsanti o righe nello stesso messaggio condividono una label. | Qualsiasi tipo con pulsanti o righe con label: pulsanti di risposta, menu a lista, caroselli multimediali | | [E15059 `WhatsAppInteractiveCarouselButtonsMismatch`](/docs/api/errors/E15059) | 422 | Le card di un carosello non hanno tutte gli stessi pulsanti. | Solo caroselli multimediali | Ogni invio interattivo può anche generare gli errori di qualsiasi invio WhatsApp: finestra di assistenza clienti chiusa, mittente mancante o non valido, destinatario non valido o contenuto ambiguo. Sono condivisi tra ogni tipo di contenuto WhatsApp, non specifici dei messaggi interattivi; consulta [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp) per quell'elenco anziché una copia qui. ## Passi successivi - [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): la request envelope, il modello `202` e i retry sicuri - [Eventi WhatsApp](/docs/guides/whatsapp/events): segui la consegna per messaggio, tramite API o webhooks - [Template WhatsApp](/docs/guides/whatsapp/templates): i messaggi che puoi ancora inviare quando la finestra è chiusa ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/products/whatsapp) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)