Sign inGet started

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.

Inviare pulsanti di risposta

Imposta interactive.type su button, con un body_text e da uno a tre buttons, ciascuno un quick_reply:
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);
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:
Esempio di codice
{
  "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 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 dell'hub per la struttura condivisa dei pulsanti.
L'header è opzionale e può assumere una di quattro forme:
Esempio di codice
"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

CampoVincolo
buttonsda 1 a 3 elementi, ciascuno un quick_reply
quick_reply.slugobbligatorio, da 1 a 256 caratteri
quick_reply.text (label)obbligatorio, da 1 a 20 caratteri, univoco nel messaggio
body_textobbligatorio, da 1 a 1024 caratteri
footer_textopzionale, da 1 a 60 caratteri
header.textda 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:
Esempio di codice
{
  "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 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. 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 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 quando l'id indica un messaggio che questo spazio di lavoro non possiede, 422 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 e Invio di messaggi WhatsApp.

Passaggi successivi