# 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 | Typ | Bird `interactive.type` | Header | Footer | Body max | | --------------------------------------------------------------------------------------------- | -------------------------- | -------------------------------------------------- | ------ | ----------------------------- | | [Antwort-Buttons](/docs/guides/whatsapp/message-types/interactive/reply-buttons) | `button` | Text, Bild, Video, Dokument | ja | 1024 | | [Listenmenüs](/docs/guides/whatsapp/message-types/interactive/list-menus) | `list` | nur Text | ja | 4096 | | [Link-Buttons](/docs/guides/whatsapp/message-types/interactive/cta-url-buttons) | `cta_url` | Text, Bild, Video, Dokument | ja | 1024 | | [Medien-Karussells](/docs/guides/whatsapp/message-types/interactive/carousels) | `carousel` | keine auf der Nachricht; Bild oder Video pro Karte | nein | 1024 Nachricht, 160 pro Karte | | [Standortanfragen](/docs/guides/whatsapp/message-types/interactive/location-requests) | `location_request_message` | keine | nein | 1024 | | [Kontaktdatenanfragen](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) | `request_contact_info` | keine | nein | 1024 | 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](/docs/guides/whatsapp/message-types#the-customer-service-window) 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](/docs/guides/whatsapp/sending-whatsapp), 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. **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/de-de/dokumentation/guides/whatsapp/message-types/interactive.ts.md) · [Python](/de-de/dokumentation/guides/whatsapp/message-types/interactive.py.md) · [Go](/de-de/dokumentation/guides/whatsapp/message-types/interactive.go.md) · [PHP](/de-de/dokumentation/guides/whatsapp/message-types/interactive.php.md) · [CLI](/de-de/dokumentation/guides/whatsapp/message-types/interactive.cli.md) · [MCP](/de-de/dokumentation/guides/whatsapp/message-types/interactive.mcp.md) · [cURL](/de-de/dokumentation/guides/whatsapp/message-types/interactive.curl.md) ## 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](/docs/guides/whatsapp/message-types/interactive/location-requests)-Nachricht, und die Antwort auf eine Kontaktdatenanfrage ist eine eingehende [Kontaktkarte](/docs/guides/whatsapp/message-types/interactive/contact-info-requests), 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](/docs/guides/whatsapp/receiving-whatsapp/interactive-replies) 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`](/docs/api/errors/E15071) fehl, weil Bird die Provider-ID, die ein Zitat benötigt, nicht mehr enthält. [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp#quoting-a-message) 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. | Code | Status | Auslöser | Betrifft | | ------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [E15055 `WhatsAppInteractiveLimitExceeded`](/docs/api/errors/E15055) | 422 | Die Nachricht überschreitet ein Limit für ihren Typ; derzeit mehr als 10 Zeilen über die Sektionen einer Liste hinweg. | Nur Listenmenüs | | [E15056 `WhatsAppInteractiveDuplicateLabel`](/docs/api/errors/E15056) | 422 | Zwei Buttons oder Zeilen in derselben Nachricht haben dasselbe Label. | Jeder Typ mit beschrifteten Buttons oder Zeilen: Antwort-Buttons, Listenmenüs, Medien-Karussells | | [E15059 `WhatsAppInteractiveCarouselButtonsMismatch`](/docs/api/errors/E15059) | 422 | Die 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](/docs/guides/whatsapp/sending-whatsapp) für diese Liste, anstatt sie hier zu kopieren. ## Nächste Schritte - [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp): der Request-Envelope, das `202`-Modell und sicheres erneutes Versuchen - [WhatsApp-Events](/docs/guides/whatsapp/events): Zustellung pro Nachricht verfolgen, über die API oder Webhooks - [WhatsApp-Templates](/docs/guides/whatsapp/templates): die Nachrichten, die Sie auch nach dem Schließen des Fensters noch senden können ## 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)