Sign inGet started

WhatsApp-Antwort-Buttons

Antwort-Buttons platzieren bis zu drei antippbare Auswahlmöglichkeiten unter einer WhatsApp-Nachricht, sodass der Empfänger mit einem Tippen statt mit Freitext antwortet. Verwenden Sie sie für eine schnelle Entscheidung, etwa das Bestätigen oder Stornieren einer Buchung. Für mehr als drei Auswahlmöglichkeiten verwenden Sie stattdessen Listenmenüs.

Antwort-Buttons senden

Setzen Sie interactive.type auf button, mit einem body_text und ein bis drei buttons, jeweils ein 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 ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete. Die vollständige Struktur fügt einen optionalen Header, Footer, ein Zitat einer früheren Nachricht und einen zweiten Button hinzu:
Codebeispiel
{
  "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 zitiert eine frühere Nachricht in derselben Konversation. Siehe im Hub Eine Nachricht zitieren, um eine Antwort zuzuordnen für die Funktionsweise der Auflösung und mögliche Lücken.
Dieser Typ sendet ausschließlich quick_reply-Buttons. Ein cta_url-Button gehört zu einem separaten interactive.type und kann nicht zusammen mit buttons erscheinen; siehe im Hub den Abschnitt Buttons für die gemeinsame Button-Struktur.
Ein Header ist optional und hat eine von vier Formen:
Codebeispiel
"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" }
Ein Media-Header (image, video oder document) übergibt seine Datei als öffentliche https-URL, die WhatsApp zum Sendezeitpunkt abruft, statt als hochgeladenes Media-Handle. footer_text ist optional und fügt eine Zeile unterhalb der Buttons hinzu.

Limits

FeldGrenze
buttons1 bis 3 Einträge, jeder ein quick_reply
quick_reply.slugerforderlich, 1 bis 256 Zeichen
quick_reply.text (Label)erforderlich, 1 bis 20 Zeichen, eindeutig pro Nachricht
body_texterforderlich, 1 bis 1.024 Zeichen
footer_textoptional, 1 bis 60 Zeichen
header.text1 bis 60 Zeichen
Bird prüft, ob Button-Labels (quick_reply.text) eindeutig sind, prüft aber nicht, ob slug-Werte eindeutig sind, obwohl jeder Slug genau einen Button identifizieren soll. Zwei Buttons mit demselben Slug werden beide gesendet und zugestellt, und ihre Antworten kommen nicht unterscheidbar zurück.

Antwort lesen

Ein Tastendruck kommt als eigene eingehende Nachricht an und enthält interactive_reply:
Codebeispiel
{
  "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"
}
Der slug, den Sie beim Senden gesetzt haben, kommt unverändert zurück, sodass Sie direkt darauf verzweigen können, ohne eine Zuordnungstabelle zu benötigen. Sie sehen diese Antwort über die Nachrichtenliste oder GET /v1/whatsapp/messages/{id}; siehe im Hub Eine Antwort lesen für den vollständigen Ablauf.

Limits und Sonderfälle

  • Das Kundenservice-Fenster muss offen sein. Antwort-Buttons sind eine Service-Nachricht und nur innerhalb eines offenen Fensters zustellbar; siehe im Hub Kundenservice-Fenster. Die Fensterprüfung schlägt offen fehl, sodass ein 202 kein Beweis dafür ist, dass das Fenster beim Versand tatsächlich offen war.
  • from muss eine Nummer sein, die Ihr Workspace besitzt. Wird sie weggelassen oder eine Nummer angegeben, die kein verbundener Absender ist, wird der Vorgang abgelehnt, bevor der Versand erstellt wird.
  • Labels müssen eindeutig sein, sonst wird der Versand abgelehnt. Zwei Buttons mit demselben quick_reply.text scheitern mit 422 E15056 WhatsAppInteractiveDuplicateLabel, weil Meta das Duplikat sonst ablehnen würde, nachdem der Versand bereits akzeptiert und berechnet wurde.
  • Das Label ist das, was der Empfänger sieht; der Slug nie. Nutzergerichteten Text in slug zu setzen ist ein stiller No-Op, da nur text im Chat dargestellt wird.
  • Eine Media-Header-URL, die WhatsApp nicht abrufen kann, schlägt nach der Annahme des Versands fehl. Bird validiert die Header-url nicht so wie die URL einer Media-Nachricht, sodass eine http://-URL oder eine, die einen Fehler zurückgibt, die Anfrage passiert und dann asynchron fehlschlägt, mit media_rejected im last_error der Nachricht.
  • Metas eigene Feldnamen zu senden lässt die Anfrage fehlschlagen. Dieser Typ lehnt unbekannte Properties sofort ab, sodass JSON, das aus Metas Cloud-API-Referenz kopiert wurde, etwa ein body-Objekt oder ein action.buttons-Wrapper, zuerst in die flachen Felder von Bird umgeformt werden muss.
Ein Zitat, das sich nicht auflösen lässt, lässt die Anfrage fehlschlagen, bevor etwas erstellt oder berechnet wird: 404 E15071, wenn die ID keine Nachricht benennt, die dieser Workspace besitzt, 422 E15072, wenn sie eine benennt, die nicht zitiert werden kann. Für die Fehler, die jeder WhatsApp-Versand auslösen kann – ein geschlossenes Fenster, ein fehlender oder ungültiger Absender oder ein ungültiger Empfänger – siehe im Hub Fehler und WhatsApp-Nachrichten senden.

Nächste Schritte