Sign inGet started

Interaktive WhatsApp-Nachrichten

Eine interaktive Nachricht besteht aus Textkörper und einem Element, das der Empfänger antippen kann: einem WhatsApp-Button, einem Menü, einem Link, einer Karte oder einer Anfrage nach Standort oder Kontaktdaten. Wo eine Template-Antwort das Parsen von Freitext erfordert, gibt ein WhatsApp-Menü oder eine Gruppe von WhatsApp-Buttons dem Empfänger eine feste Auswahl und liefert Ihnen einen von Ihnen definierten Wert zurück. Diese Seite behandelt, was die sechs Typen gemeinsam haben; die eigene Seite jedes Typs beschreibt seine Nachrichtenstruktur und seine spezifischen Limits.

Die sechs Typen

TypBird interactive.typeHeaderFooterBody max
Antwort-ButtonsbuttonText, Bild, Video, Dokumentja1024
Listenmenüslistnur Textja4096
Link-Buttonscta_urlText, Bild, Video, Dokumentja1024
Medien-Karussellscarouselkeine auf der Nachricht; Bild oder Video pro Kartenein1024 Nachricht, 160 pro Karte
Standortanfragenlocation_request_messagekeinenein1024
Kontaktdatenanfragenrequest_contact_infokeinenein1024
Alle Typen sind Freiform-Nachrichten: Sie können nur innerhalb eines offenen Kundenservice-Fensters zugestellt werden und werden nie von Meta geprüft, wie es bei einem Template der Fall ist.
Interaktive Nachrichten sind Freiform-Inhalte, daher gilt die Kundenservice-Fenster-Regel: Unter Das Kundenservice-Fenster erfahren Sie, was das bedeutet und was ein geschlossenes Fenster zurückgibt.
Jeder interaktive Versand erfordert außerdem from, eine Nummer, die Ihrem Workspace gehört. Die verwalteten Nummern von Bird unterstützen das nicht, daher benötigt ein interaktiver Versand eine eigene, zuvor verbundene Nummer.

Der interactive-Content-Zweig

interactive ist eines der sich gegenseitig ausschließenden Content-Felder auf POST /v1/whatsapp/messages, neben template, text, image und den übrigen: Genau eines darf bei einem Versand vorhanden sein. Innerhalb von interactive benennt type, welche der sechs Varianten vorliegt, und das eigene Feld dieser Variante enthält den Rest (buttons, list, cta_url oder cards). Das Schema sperrt die Felder aller anderen Varianten, sodass das Mischen zweier Varianten in einem Versand die Validierung nicht besteht, bevor es einen Handler erreicht.
Für den Request-Envelope, das 202-Response-Modell und sicheres erneutes Versuchen siehe WhatsApp-Nachrichten senden, anstatt sie auf dieser Seite erneut zu erklären.
Hier ist eine minimale interaktive Nachricht: zwei WhatsApp-Buttons in einem Reply-Buttons-Versand, jeweils eine Sprache.
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);

Buttons

Vier der sechs Typen platzieren einen Button, und alle verwenden dieselbe Form: ein diskriminiertes Objekt, dessen type entweder quick_reply oder cta_url ist, jeweils mit einem eigenen verschachtelten Feld gleichen Namens. Ein quick_reply-Button enthält slug und text; ein cta_url-Button enthält text und url. Welche Typen welche Button-Form akzeptieren:
  • Antwort-Buttons senden nur quick_reply-Buttons, 1 bis 3 Stück.
  • Link-Buttons senden genau einen cta_url-Button.
  • Medien-Karussells platzieren Buttons auf jeder Karte: entweder einen cta_url-Button oder bis zu drei quick_reply-Buttons, und jede Karte im Karussell muss übereinstimmen.
  • Listenmenüs verwenden Zeilen innerhalb von Sektionen anstelle dieses Button-Objekts; siehe deren eigene Seite.
Die slug eines quick_reply-Buttons ist Ihr eigenes Handle für diesen Button. Sie wird dem Empfänger nie angezeigt, nur das text-Label ist sichtbar, und die slug wird in der Antwort wortgetreu zurückgegeben. Dieser Roundtrip macht eine Antwort dem Button zuordenbar, der sie ausgelöst hat, daher wird das einmal hier erklärt und nicht auf jeder Einzelseite.

Eine Antwort lesen

Das Drücken eines Buttons oder Auswählen einer Menüzeile sendet eine eigene eingehende Nachricht mit einem interactive_reply-Objekt. interactive_reply.type ist button oder list; in beiden Fällen enthält das verschachtelte Objekt die von Ihnen deklarierte slug und text, das angetippte Label, das der Empfänger tatsächlich gesehen hat. Die zwei Anfragetypen, Standortanfragen und Kontaktdatenanfragen, antworten anders: Die Antwort auf eine Standortanfrage ist eine gewöhnliche eingehende Standort-Nachricht, und die Antwort auf eine Kontaktdatenanfrage ist eine eingehende Kontaktkarte, kein interactive_reply.
Eine Antwort erreicht Sie über die Nachrichtenliste und GET /v1/whatsapp/messages/{id}, genauso wie jede eingehende WhatsApp-Nachricht. Um auf eine Antwort bei Eingang zu reagieren statt zu pollen, abonnieren Sie den whatsapp.received-Webhook: Sein Payload enthält interactive_reply, benennt also bereits den angetippten Button oder die Zeile. Interaktive Antworten empfangen beschreibt die Leseform eines Taps, den Webhook-Payload und die Taps, die auf einem anderen Zweig ankommen.

Eine Nachricht zitieren, um eine Antwort zuzuordnen

in_reply_to_message_id auf einem Versand zitiert eine frühere Nachricht aus derselben Konversation, und jede Nachricht, gesendet oder empfangen, gibt es beim Lesen zurück. Es ist ein Feld für beide Richtungen.
Die Zuordnung, die das ermöglicht, ist asymmetrisch. Ein Tap auf einen WhatsApp-Button oder eine Menüzeile enthält Metas eigene context, sodass in_reply_to_message_id auf die Nachricht auflöst, die ihn angeboten hat. Eine geteilte Kontaktkarte enthält keine context, löst also auf nichts auf: Sie ordnen die Antwort einer Kontaktdatenanfrage über from und Timing zu, nicht über dieses Feld.
Die Auflösung läuft über einen Message-Context-Store, und ein Fehlschlag lässt das Feld weg, anstatt eines zu melden. Das ist auf der Leitung nicht von einer Antwort zu unterscheiden, die auf gar nichts antwortet. Eine Integration, die zuverlässige Zuordnung braucht, sollte sich nicht allein auf dieses Feld verlassen: Senden Sie Ihre eigene metadata mit und gleichen Sie darüber ab.
Das Zeitfenster, in dem eine Nachricht zitierbar bleibt, ist auf 15 Tage begrenzt; danach schlägt der Versand mit einem 404 E15071 fehl, weil Bird die Provider-ID, die ein Zitat benötigt, nicht mehr enthält. WhatsApp-Nachrichten senden beschreibt das sendeseitige Feld: seine Länge, seine Auflösung und die Request-Struktur.

Fehler

Drei Fehlercodes sind spezifisch für interaktiven Content. Jeder wird nur bei den Typen ausgelöst, die das geprüfte Feld besitzen, daher benennt die vierte Spalte, welche Typen tatsächlich betroffen sein können.
CodeStatusAuslöserBetrifft
E15055 WhatsAppInteractiveLimitExceeded422Die Nachricht überschreitet ein Limit für ihren Typ; derzeit mehr als 10 Zeilen über die Sektionen einer Liste hinweg.Nur Listenmenüs
E15056 WhatsAppInteractiveDuplicateLabel422Zwei Buttons oder Zeilen in derselben Nachricht haben dasselbe Label.Jeder Typ mit beschrifteten Buttons oder Zeilen: Antwort-Buttons, Listenmenüs, Medien-Karussells
E15059 WhatsAppInteractiveCarouselButtonsMismatch422Die Karten eines Karussells tragen nicht alle dieselben Buttons.Nur Medien-Karussells
Jeder interaktive Versand kann auch die Fehler auslösen, die jeder WhatsApp-Versand auslösen kann: ein geschlossenes Kundenservice-Fenster, ein fehlender oder ungültiger Absender, ein ungültiger Empfänger oder mehrdeutiger Content. Diese gelten für jeden WhatsApp-Content-Typ und sind nicht spezifisch für interaktive Nachrichten; siehe WhatsApp-Nachrichten senden für diese Liste, anstatt sie hier zu kopieren.

Nächste Schritte