WhatsApp-Reaktionen empfangen
Abonnieren Sie Reaktionsänderungen, um zu erfahren, wann ein Kontakt ein Emoji zu einer Ihrer Nachrichten hinzufügt, es ändert oder zurücknimmt. Reaktionen sind Annotationen einer bestehenden Nachricht und treffen über whatsapp.reacted ein.
Voraussetzungen
Richten Sie einen Webhook-Endpunkt für Ihren Workspace ein. Um die aktuellen Reaktionen oder deren Verlauf abzurufen, verwenden Sie einen API-Schlüssel mit WhatsApp-Leseberechtigung.
1. Reaktionsänderungen abonnieren
Fügen Sie whatsapp.reacted zu Ihrem Webhook-Abonnement hinzu. Ein Abonnement von whatsapp.received enthält keine Reaktionen. Folgen Sie dem Webhooks-Leitfaden für Signaturprüfung, Zustellungswiederholungen und Endpunktkonfiguration.
Reaktionen erzeugen keine neue Nachricht in der Nachrichtenliste und öffnen kein Kundenservice-Fenster. Wenn Sie antworten möchten, prüfen Sie die Service-Window-Regeln, bevor Sie eine Freitext-Nachricht senden.
2. Nachricht und Änderung identifizieren
Lesen Sie data.whatsapp_id des Events, um die Nachricht zu finden, auf die der Kontakt reagiert hat. Dies ist die ursprüngliche Bird-Nachrichten-ID (wam_…), keine separate Reaktions-ID.
Verwenden Sie data.from, um den Kontakt zu identifizieren, und data.to, um Ihren WhatsApp-Absender zu identifizieren. Dies sind WhatsApp-Adressobjekte; behandeln Sie geschäftsbereichsbezogene Benutzer-IDs, wenn die Adresse des Kontakts keine Telefonnummer enthält.
Ein Kontakt, der eine Daumen-hoch-Reaktion hinzufügt, erzeugt diesen Webhook:
Codebeispiel
{
"data": {
"emoji": "👍",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
},
"timestamp": "2026-08-28T19:01:10.000Z",
"type": "whatsapp.reacted"
}Interpretieren Sie data.emoji wie folgt:
- Ein Emoji ungleich null fügt die Reaktion des Kontakts auf die referenzierte Nachricht hinzu oder ersetzt sie.
- Ein null-Emoji entfernt die Reaktion des Kontakts. Das Feld ist bei einem Entfernungsevent vorhanden.
Ein Ersatz kommt als einzelnes Event mit dem neuen Emoji an; es gibt kein separates Entfernungsevent für das alte Emoji. Bewahren Sie den exakten String: ❤ und ❤️ sind unterschiedliche Werte im Payload.
3. Aktuelle Reaktionen abrufen
Wenn Ihre Anwendung die aktuell an einer Nachricht angehängte Reaktion anzeigt, rufen Sie die Nachricht ab und lesen Sie reactions. Die Liste enthält eine bestehende Reaktion pro Absender und wird weggelassen, wenn keine Reaktionen vorhanden sind.
Für GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te haben die reaktionsbezogenen Felder diese Form (andere Nachrichtenfelder weggelassen):
Codebeispiel
{
"id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
"reactions": [
{
"emoji": "👍",
"from": { "phone_number": "+14155550100" }
}
]
}Die Nachricht behält ihren ursprünglichen Inhalt, ihre Richtung und ihren Zustellstatus. reactions[].from identifiziert die Person, die reagiert hat.
Behandeln Sie den letzten empfangenen Webhook nicht als aktuellen Zustand. WhatsApp meldet Reaktionszeiten sekundengenau, sodass Änderungen denselben Zeitstempel teilen können und Webhook-Wiederholungen die Ankunftsreihenfolge ändern können. Verwenden Sie Webhooks, um eine Aktualisierung der aktuellen Reaktionen der Nachricht auszulösen.
4. Reaktionsverlauf prüfen
Listen Sie Reaktionsevents auf, um Änderungen an der referenzierten Nachricht zu prüfen. Eingehende Kontaktänderungen haben den Status received; eine Entfernung trägt emoji: null. Die Liste enthält auch Ergebnisse von Reaktionen, die Ihr Workspace gesendet hat.
Der Reaction-Events-Endpunkt API gibt eine paginierte Antwort zurück. Dieses Beispiel zeigt eine abgelehnte Geschäftsreaktion und eine zuvor empfangene Kontaktreaktion:
Codebeispiel
{
"data": [
{
"id": "war_01krdgeqcxet5s7t44vh8rt9mh",
"emoji": "🎉",
"status": "rejected",
"from": {
"phone_number": "+13124495569"
},
"error": {
"code": "internal_error",
"description": "the receiving number is no longer connected",
"occurred_at": "2026-08-28T19:04:22Z"
},
"occurred_at": "2026-08-28T19:04:22Z"
},
{
"id": "war_01krdgeqcxet5s7t44vh8rt9mg",
"emoji": "👍",
"status": "received",
"from": {
"phone_number": "+14155550100",
"bsuid": "US.13491208655302741918"
},
"occurred_at": "2026-08-28T19:01:10Z"
}
],
"next_cursor": null,
"prev_cursor": null,
"refresh_cursor": "eyJ2IjoxLCJzIjoiMjAyNi0wOC0yOFQxOTowNDoyMloiLCJpIjoiMDE5ZTFiMDctNWQ5ZC03NjhiLTkzZTgtODRkYzUxOGQyNjkxIn0"
}Der Reaktionsverlauf ist vom Zustellverlauf der Nachricht getrennt. Der Message-Events-Endpunkt enthält keine whatsapp.reacted-Änderungen. Für Aufbewahrung und Paginierung folgen Sie der Reaktionslog-Referenz.
Fehlerbehebung
- Kein Reaktions-Webhook: Prüfen Sie, ob das Abonnement whatsapp.reacted enthält. Eine Reaktion auf eine ältere Nachricht, deren Provider-Referenz nicht mehr aufgelöst werden kann, erzeugt keine zugeordnete Reaktion, keinen Logeintrag und keinen Webhook.
- Reaktion fehlt in der Nachrichtenliste: Suchen Sie die Originalnachricht. Eine Reaktion ist an diese angehängt und hat keine eigene Nachrichtenzeile.
- Reaktionsstatus ändert sich unerwartet: Aktualisieren Sie reactions der Originalnachricht, statt Webhook-Events nach Ankunftszeit oder Zeitstempel zu ordnen.
Nächste Schritte
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten