# Pulsanti di risposta WhatsApp

I pulsanti di risposta aggiungono fino a tre scelte tappabili sotto un messaggio WhatsApp, così il destinatario risponde con un tap invece di digitare testo libero. Usali per una decisione rapida, come confermare o annullare una prenotazione. Per più di tre scelte, usa i [menu a lista](/docs/guides/whatsapp/message-types/interactive/list-menus).

## Inviare pulsanti di risposta

Imposta `interactive.type` su `button`, con un `body_text` e da uno a tre `buttons`, ciascuno un `quick_reply`:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  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" } }],
  },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.ts.md) · [Python](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.py.md) · [Go](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.go.md) · [PHP](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.php.md) · [CLI](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.cli.md) · [MCP](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.mcp.md) · [cURL](/it-it/documentazione/guides/whatsapp/message-types/interactive/reply-buttons.curl.md)

`from` è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. La struttura completa aggiunge un header opzionale, un footer, la citazione di un messaggio precedente e un secondo pulsante:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
    "footer_text": "Lucky Shrub, your gateway to succulents",
    "buttons": [
      { "type": "quick_reply", "quick_reply": { "slug": "change-booking", "text": "Change" } },
      { "type": "quick_reply", "quick_reply": { "slug": "cancel-booking", "text": "Cancel" } }
    ]
  },
  "tags": [{ "name": "category", "value": "booking" }],
  "metadata": { "order_id": "A-1" }
}
```

`in_reply_to_message_id` cita un messaggio precedente nella stessa conversazione. Consulta la sezione dell'hub [citare un messaggio per correlare una risposta](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply) per il funzionamento della risoluzione e i casi che può mancare.

Questo tipo invia solo pulsanti `quick_reply`. Un pulsante `cta_url` appartiene a un `interactive.type` separato e non può comparire insieme a `buttons`; consulta la sezione [pulsanti](/docs/guides/whatsapp/message-types/interactive#buttons) dell'hub per la struttura condivisa dei pulsanti.

## Header e footer

L'header è opzionale e può assumere una di quattro forme:

```text
"header": { "type": "text",     "text": "New workshop dates" }
"header": { "type": "image",    "url": "https://cdn.example.com/a.png" }
"header": { "type": "video",    "url": "https://cdn.example.com/a.mp4" }
"header": { "type": "document", "url": "https://cdn.example.com/a.pdf" }
```

Un header multimediale (`image`, `video` o `document`) trasporta il file come URL `https` pubblico che WhatsApp recupera al momento dell'invio, anziché come handle di un media caricato. `footer_text` è opzionale e aggiunge una riga sotto i pulsanti.

## Limiti

| Campo                      | Vincolo                                                  |
| -------------------------- | -------------------------------------------------------- |
| `buttons`                  | da 1 a 3 elementi, ciascuno un `quick_reply`             |
| `quick_reply.slug`         | obbligatorio, da 1 a 256 caratteri                       |
| `quick_reply.text` (label) | obbligatorio, da 1 a 20 caratteri, univoco nel messaggio |
| `body_text`                | obbligatorio, da 1 a 1024 caratteri                      |
| `footer_text`              | opzionale, da 1 a 60 caratteri                           |
| `header.text`              | da 1 a 60 caratteri                                      |

Bird verifica che le label dei pulsanti (`quick_reply.text`) siano univoche, ma non verifica che i valori `slug` siano univoci, anche se ogni slug è pensato per identificare un singolo pulsante. Due pulsanti con lo stesso slug vengono entrambi inviati e recapitati, e le rispettive risposte tornano indistinguibili.

## Leggere la risposta

La pressione arriva come messaggio in entrata a sé stante, con `interactive_reply`:

```json
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "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"
}
```

Il `slug` impostato all'invio torna identico, quindi puoi usarlo direttamente per il branching senza una tabella di corrispondenza. Puoi vedere questa risposta tramite la lista messaggi o `GET /v1/whatsapp/messages/{id}`; consulta la sezione dell'hub [leggere una risposta](/docs/guides/whatsapp/message-types/interactive#reading-a-reply) per il percorso completo.

## Limiti e casi particolari

- **La finestra del servizio clienti deve essere aperta.** I pulsanti di risposta sono un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; consulta la sezione dell'hub [finestra del servizio clienti](/docs/guides/whatsapp/message-types#the-customer-service-window). Il controllo della finestra fallisce in modo aperto, quindi un `202` non è prova che la finestra fosse effettivamente aperta al momento dell'invio.
- **`from` deve essere un numero di proprietà del tuo spazio di lavoro.** Ometterlo, o indicare un numero che non è un sender connesso, viene rifiutato prima che l'invio sia creato.
- **Le label devono essere univoche, altrimenti l'invio viene rifiutato.** Due pulsanti con lo stesso `quick_reply.text` falliscono con `422` [`E15056`](/docs/api/errors/E15056) `WhatsAppInteractiveDuplicateLabel`, perché Meta rifiuterebbe comunque il duplicato dopo che l'invio è già stato accettato e addebitato.
- **La label è ciò che il destinatario vede; lo slug non lo è mai.** Inserire testo destinato all'utente in `slug` è un no-op silenzioso, perché solo `text` viene visualizzato nella chat.
- **Un URL di header multimediale che WhatsApp non riesce a recuperare fallisce dopo che l'invio è stato accettato.** Bird non valida l'header `url` come valida l'URL di un messaggio multimediale, quindi un URL `http://` o uno che restituisce un errore supera la richiesta e poi fallisce in modo asincrono, con `media_rejected` sul `last_error` del messaggio.
- **Inviare i nomi di campo propri di Meta fa fallire la richiesta.** Questo tipo rifiuta le proprietà sconosciute senza eccezione, quindi JSON copiato dal riferimento Cloud API di Meta, come un oggetto `body` o un wrapper `action.buttons`, va ristrutturato nei campi piatti di Bird.

Una citazione che non viene risolta fa fallire la richiesta prima che qualsiasi cosa venga creata o addebitata: `404` [`E15071`](/docs/api/errors/E15071) quando l'id indica un messaggio che questo spazio di lavoro non possiede, `422` [`E15072`](/docs/api/errors/E15072) quando indica un messaggio che non può essere citato. Per gli errori che qualsiasi invio WhatsApp può incontrare, una finestra chiusa, un sender mancante o non valido, o un destinatario non valido, consulta le sezioni dell'hub [errori](/docs/guides/whatsapp/message-types/interactive#errors) e [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp).

## Passaggi successivi

- [Messaggi interattivi WhatsApp](/docs/guides/whatsapp/message-types/interactive): ciò che tutti e sei i tipi interattivi hanno in comune
- [Menu a lista](/docs/guides/whatsapp/message-types/interactive/list-menus): per più di tre scelte
- [Invio di messaggi WhatsApp](/docs/guides/whatsapp/sending-whatsapp): l'envelope della richiesta, il modello `202` e i tentativi sicuri di riprovare

## 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)