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);msg = client.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"}}],
},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Interactive: &bird.WhatsAppInteractiveSend{
Type: "button",
BodyText: "Your gardening workshop is scheduled for 9am tomorrow.",
Buttons: &[]bird.WhatsAppInteractiveButtonSend{
{Type: "quick_reply", QuickReply: &bird.WhatsAppInteractiveQuickReplyButtonSend{Slug: "change-booking", Text: "Change"}},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$interactive = (new WhatsAppMessageSendRequestInteractive())
->setType('button')
->setBodyText('Your gardening workshop is scheduled for 9am tomorrow.')
->setButtons([
(new WhatsAppInteractiveButtonSend())
->setType('quick_reply')
->setQuickReply((new WhatsAppInteractiveButtonSendQuickReply())->setSlug('change-booking')->setText('Change')),
]);
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--interactive '{"body_text":"Your gardening workshop is scheduled for 9am tomorrow.","buttons":[{"quick_reply":{"slug":"change-booking","text":"Change"},"type":"quick_reply"}],"type":"button"}' \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"interactive": {
"body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
"buttons": [
{
"quick_reply": {
"slug": "change-booking",
"text": "Change"
},
"type": "quick_reply"
}
],
"type": "button"
},
"to": "+16505551234"
}
}curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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" } }
]
}
}'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.
Header e footer
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
| 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:
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
- Messaggi interattivi WhatsApp: ciò che tutti e sei i tipi interattivi hanno in comune
- Menu a lista: per più di tre scelte
- Invio di messaggi WhatsApp: l'envelope della richiesta, il modello 202 e i tentativi sicuri di riprovare
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 channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione