WhatsApp-Reaktionsereignisse

Eine Emoji-Reaktion ergänzt eine bestehende Nachricht, anstatt eine neue zu erstellen. Sie erscheint daher nie als eigenständige Nachricht oder unter den Nachrichtenstatusereignissen. Bird speichert stattdessen zwei Ansichten: die aktuell auf der Nachricht stehenden Reaktionen und ein Protokoll jeder Änderung, die dazu geführt hat. Beide erfassen Änderungen durch den Kontakt und durch Ihre Geschäftsnummer.

Um über die Reaktion eines Kontakts in Echtzeit informiert zu werden, abonnieren Sie whatsapp.reacted. Um eigene Reaktionen hinzuzufügen oder zu entfernen, siehe Reaktionen senden.

Voraussetzungen

Ein API-Schlüssel mit WhatsApp-Leseberechtigung und die ID (wam_…) der Nachricht, auf die reagiert wurde.

1. Aktuelle Reaktionen lesen

Wenn Ihre Anwendung die aktuell an einer Nachricht angehängte Reaktion anzeigt, rufen Sie die Nachricht ab und lesen Sie deren reactions. Die Liste enthält eine stehende 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):

{
  "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.

Dies ist der anzuzeigende Zustand. Reaktions-Webhooks können denselben Zeitstempel haben und in falscher Reihenfolge eintreffen. Verwenden Sie einen Webhook daher als Auslöser, die Nachricht erneut abzurufen, nicht als aktuellen Zustand.

2. Reaktionsprotokoll lesen

Reaktionsereignisse auflisten mit GET /v1/whatsapp/messages/{message_id}/reaction-events, um jede Änderung an der referenzierten Nachricht zu sehen, neueste zuerst: Hinzufügungen, Ersetzungen und Entfernungen. Jeder Eintrag hat eine Reaktions-ID (war_…), den emoji, wer die Änderung vorgenommen hat in from, einen occurred_at-Zeitstempel und einen status:

• received: eine Änderung durch einen Kontakt.
• sent: WhatsApp hat eine Änderung durch Ihre Geschäftsnummer akzeptiert.
• failed: WhatsApp hat Ihre Änderung abgelehnt.
• rejected: Bird hat Ihre Änderung vor dem Senden abgelehnt.

Ein failed- oder rejected-Eintrag enthält den Grund in error. Eine Entfernung enthält emoji: null. Eine noch ausstehende eigene Änderung hat keinen Eintrag, bis ihr Ergebnis feststeht. Reaktionen werden nie berechnet, daher handelt es sich bei keinem Fehler hier um einen Abrechnungsfehler.

Der Reaktionsereignis-API gibt eine paginierte Antwort zurück. Dieses Beispiel zeigt eine abgelehnte Geschäftsreaktion und eine zuvor empfangene Kontaktreaktion:

{
  "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"
}

Die Reaktionshistorie ist von den Zustellungsereignissen der Nachricht getrennt. Der Endpunkt Nachrichtenstatusereignisse enthält keine whatsapp.reacted-Änderungen. Für Aufbewahrung und Paginierung folgen Sie der Reaktionsprotokoll-Referenz.

Fehlerbehebung

• Reaktion fehlt in der Nachrichtenliste: Rufen Sie die ursprüngliche Nachricht auf. Eine Reaktion ist an sie angehängt und hat keine eigene Nachrichtenzeile.
• Reaktionszustand ändert sich unerwartet: Lesen Sie reactions der Nachricht, statt Webhook-Ereignisse nach Eingangszeit oder Zeitstempel zu sortieren.

Nächste Schritte

• Reaktions-Webhooks: Benachrichtigung erhalten, wenn ein Kontakt reagiert
• Reaktion senden oder entfernen
• Nachrichtenstatusereignisse: der Zustellungsverlauf einer Nachricht