WhatsApp-Gruppennachrichten empfangen

Alles, was ein Teilnehmer in einer Gruppe schreibt, kommt genauso an wie jede andere eingehende WhatsApp-Nachricht: dasselbe whatsapp.received-Event, dieselben Content-Arms, derselbe Medienabruf. Zwei Dinge sind gruppenspezifisch. Die Nachricht nennt sowohl den Teilnehmer, der sie geschrieben hat, als auch die Gruppe, über die sie kam, und Ihre Antwort geht an die Gruppe statt an diese Person.

WhatsApp-Nachrichten empfangen behandelt die Teile, die nicht gruppenspezifisch sind: jeden Content-Arm, eingehende Medien abrufen und zitierte Antworten.

Was eine Gruppennachricht enthält

Eine eingehende Gruppennachricht wird mit zwei Adressen statt einer zurückgelesen:

• from ist der Teilnehmer, der sie geschrieben hat, nie die Gruppe. Es enthält die bsuid (Business-scoped User ID), die phone_number, wenn Ihr Unternehmen sie kennt, sowie username und display_name, wenn der Teilnehmer ein Profil veröffentlicht. Ein Teilnehmer, der seine Nummer nicht mit Ihnen geteilt hat, wird allein durch die bsuid identifiziert, und das reicht aus, um ihn zu adressieren.
• to enthält Ihre Geschäftsnummer und die Gruppe. phone_number ist die Nummer, die die Nachricht empfangen hat, und group_id ist die Gruppe, über die sie ankam.

group_id erscheint auf to und nirgendwo sonst. Sein Vorhandensein dort unterscheidet eine Gruppennachricht von einer Einzelnachricht, in beide Richtungen. Eine Gruppennachricht enthält keine Zähler: recipient_count, delivered_count und read_count melden einen ausgehenden Fan-out, und eine eingehende Nachricht hat keinen.

Um den Thread einer Gruppe in beide Richtungen gleichzeitig zu lesen, filtern Sie die Nachrichtenliste nach group_id, wie An eine WhatsApp-Gruppe senden zeigt.

Der Gruppe antworten

Wenn ein Teilnehmer in der Gruppe schreibt, öffnet das ein einzelnes 24-Stunden-Kundenservice-Fenster für die gesamte Gruppe, nicht eines pro Person. Solange es offen ist, erreicht Freiform-Inhalt die Gruppe; sobald es abläuft, ist ein Template erforderlich. Adressieren Sie die Antwort an die Gruppe, mit der Gruppen-ID in to und ohne from. Siehe An eine WhatsApp-Gruppe senden.

Dem Teilnehmer privat zu schreiben ist eine separate Konversation mit eigenem Fenster, und die Gruppennachricht öffnet es nicht. Eine Freiform-Nachricht an dessen Telefonnummer oder bsuid wird mit einem 422 E15044 abgelehnt, es sei denn, der Teilnehmer hat Ihr Unternehmen in den letzten 24 Stunden separat kontaktiert. Ein Template erreicht ihn in jedem Fall.

Bestätigen und reagieren

Beide Bestätigungen funktionieren bei einer Gruppennachricht und verwenden dieselben Aufrufe wie bei jeder anderen eingehenden Nachricht:

• Als gelesen markieren mit der ID der Nachricht. Am Aufruf ändert sich für eine Gruppe nichts.
• Darauf reagieren mit einem Emoji. Die Reaktion geht an die Gruppe, sodass jeder Teilnehmer sie sieht. Eine nicht aktive Gruppe lehnt die Änderung mit einem 409 E15047 ab – die einzige Ablehnung, die eine Reaktion auf eine Gruppennachricht hat und eine Einzelreaktion nicht.

Der Webhook

whatsapp.received liefert eine Gruppennachricht im selben Envelope wie jede andere, mit der Gruppe auf to:

{
  "type": "whatsapp.received",
  "timestamp": "2026-09-15T14:05:41.204Z",
  "data": {
    "whatsapp_id": "wam_01kya1b3xdq7fe8m2v5t9rncgs",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+15550002222", "bsuid": "US.AbC1", "display_name": "Dana Reyes" },
    "to": { "phone_number": "+15550001111", "group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg" },
    "text": { "body": "Got it, thanks." },
    "tags": null,
    "metadata": null
  }
}

Lesen Sie data.to.group_id, um die Nachricht dem Thread der Gruppe zuzuordnen, und data.from, um sie einem Teilnehmer zuzuweisen. Ein Subscriber, der Konversationen nur nach from schlüsselt, ordnet jeden Teilnehmer einer Gruppe einem separaten Thread zu und verliert die Gruppe.

Für die Gruppe selbst gibt es kein Event. Beitritt, Austritt, Namensänderung oder Anpinnen einer Nachricht erzeugen keinen Webhook. Die Mitgliedschaft einer Gruppe wird daher gelesen, nicht gepusht: Öffnen Sie die Gruppe auf der Seite Groups, oder lesen Sie sie aus, wie WhatsApp-Gruppen verwalten zeigt.

Nächste Schritte

• An eine WhatsApp-Gruppe senden: die Gruppe adressieren, was dafür nötig ist und die Empfangsbestätigungen pro Teilnehmer
• WhatsApp-Gruppen verwalten: eine Gruppe über die API erstellen, Einladungslinks, Beitrittsanfragen und Pins
• WhatsApp-Gruppen: wozu eine Gruppe dient und welche Einschränkungen WhatsApp setzt
• WhatsApp-Nachrichten empfangen: alle Inhaltstypen, Medien und zitierte Antworten
• Business-scoped User IDs: einen Teilnehmer adressieren, dessen Telefonnummer Sie nicht haben