An eine WhatsApp-Gruppe senden

Ein Gruppenversand ist ein gewöhnlicher POST /v1/whatsapp/messages, dessen to statt einer Person eine Gruppe benennt: ein Request, eine Nachricht, und jeder Teilnehmer dieses Gruppenchats empfängt sie und kann dort antworten, wo die anderen es sehen. Was sich ändert, ist das Reporting. Die Nachricht enthält Zähler dafür, wie viele Teilnehmer sie erreicht hat, und die Zustellung wird pro Teilnehmer einzeln bestätigt.

Das Erstellen und Verwalten einer Gruppe ist vom Senden an sie getrennt. WhatsApp-Gruppen verwalten behandelt das Erstellen über die API und das Teilen des Einladungslinks, und WhatsApp-Gruppen behandelt den Zweck einer Gruppe und die Einschränkungen, die WhatsApp vorgibt.

Voraussetzungen

Sie benötigen einen API-Schlüssel mit WhatsApp-Schreibberechtigung und die ID einer Gruppe im Status Active (wag_…). Kopieren Sie diese im Tab Details der Gruppe auf der Seite Groups, lesen Sie sie aus to.group_id einer Nachricht, die über die Gruppe eingegangen ist, oder listen Sie Ihre Gruppen auf.

Ersetzen Sie die Beispiel-Gruppen-ID durch Ihre eigene. Initialisieren Sie den Client für Ihre Sprache mithilfe der TypeScript-, Python-, Go- oder PHP-Anleitung für SDK. Für CLI-Beispiele installieren und authentifizieren Sie die CLI mit WhatsApp-Schreibzugriff. Verwenden Sie den API-Host für Ihre Workspace-Region in cURL-Requests.

1. Nachricht senden

Setzen Sie die Gruppen-ID in to und lassen Sie from weg. Eine Gruppe ist an die Geschäftsnummer gebunden, mit der sie erstellt wurde; daher ist diese Nummer die einzige, über die die Nachricht gesendet werden kann. Die Angabe eines Absenders gibt eine 422-E15018 zurück.

const msg = await bird.whatsapp.send({
  to: "wag_01krdgeqcxet5s7t44vh8rt9mg",
  text: { body: "The route sheet for Tuesday is up." },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="wag_01krdgeqcxet5s7t44vh8rt9mg",
    text={"body": "The route sheet for Tuesday is up."},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:   "wag_01krdgeqcxet5s7t44vh8rt9mg",
	Text: &bird.WhatsAppTextSend{Body: "The route sheet for Tuesday is up."},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$text = (new WhatsAppMessageSendRequestText())
    ->setBody("The route sheet for Tuesday is up.");
$message = $bird->whatsapp->send(
    to: 'wag_01krdgeqcxet5s7t44vh8rt9mg',
    text: $text,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --text 'The route sheet for Tuesday is up.' \
  --to wag_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "wag_01krdgeqcxet5s7t44vh8rt9mg",
      "text": { "body": "The route sheet for Tuesday is up." }
    }'

Der API gibt 202 zurück, mit der Gruppe auf to.group_id, status: accepted und recipient_count: wie viele Personen in der Gruppe waren, als der Versand angenommen wurde. Dieser Wert ist der Nenner für alles in Schritt 3 und wird in diesem Moment fixiert. Jemand, der über den Einladungslink beitritt, während die Nachricht unterwegs ist, empfängt sie nicht und ändert den Wert nicht.

2. Was eine Gruppe akzeptiert

Eine Gruppe akzeptiert Text, Bilder, Video, Audio, Sticker, Dokumente, einen Standort, Kontaktkarten und ein Template, das Ihr Workspace in einer beliebigen Kategorie außer Authentifizierung erstellt hat. Zwei Arten von Inhalten werden mit einer 422-E15052 abgelehnt, bevor die Nachricht erstellt oder berechnet wird, weil WhatsApp keine davon an einen Gruppenchat zustellt:

• Alles Interaktive: Antwort-Buttons, Listenmenüs, Link-Buttons, Karussells sowie Standort- und Kontaktdatenanfragen.
• Ein Authentifizierungs-Template. Senden Sie den Bestätigungscode stattdessen direkt an den Teilnehmer.

Ein Bird-verwaltetes Template wird von einer Bird-eigenen Nummer gesendet, die nie die Nummer ist, an die eine Gruppe gebunden ist. Daher gibt das Adressieren an eine Gruppe eine 422-E15001 zurück.

Freiform-Inhalte erfordern weiterhin ein offenes Kundenservice-Fenster, und eine Gruppe hat ein eigenes: Jeder Teilnehmer, der in die Gruppe schreibt, öffnet ein einzelnes 24-Stunden-Fenster für die gesamte Gruppe. Schreibt dieselbe Person Ihnen außerhalb der Gruppe, öffnet das dieses Fenster nicht. Sobald das Fenster abläuft, erreicht nur noch ein Template die Gruppe.

3. Den Fan-out verfolgen

Rufen Sie die Nachricht ab, um zu sehen, wie weit sie gelangt ist. Drei Zähler berichten über den Fan-out:

Bei einer Gruppennachricht gibt status den am weitesten erreichten Punkt an, den jeder Empfänger erreicht hat: Er wechselt erst auf delivered, wenn delivered_count gleich recipient_count ist, und bleibt auf sent, solange manche bestätigt haben und andere nicht. Keine WhatsApp-Nachricht hat einen read-Status, daher wird das Lesen über read_count und read_at abgebildet. delivered_at und read_at stammen vom ersten Empfänger, nicht vom letzten. failed und rejected gelten nie pro Teilnehmer, weil es eine einzige Übergabe an WhatsApp gibt und nur eine Möglichkeit, sie abzulehnen.

Ein Versand an eine Gruppe, der noch niemand beigetreten war, enthält gar keine Zähler, da es keinen Nenner gibt. Verwenden Sie daher to.group_id statt der Zähler, um eine Gruppennachricht von einer Einzelnachricht zu unterscheiden.

Um zu sehen, welchen Teilnehmer eine Bestätigung betrifft, listen Sie die Events der Nachricht auf. Ein Gruppenversand wird pro Teilnehmer in höchstens ein whatsapp.delivered und höchstens ein whatsapp.read aufgefächert, jeweils mit recipient, das die Telefonnummer der Person, ihre geschäftsbezogene Nutzer-ID oder beides enthält. Keines von beiden ist für irgendjemanden garantiert: WhatsApp überspringt die Zustellbestätigung für einen Teilnehmer, der den Chat bereits geöffnet hat, und eine Lesebestätigung kommt nur an, wenn die Person die Nachricht öffnet. Zählen Sie, was ankommt, anstatt pro Teilnehmer auf je eine Bestätigung zu warten, und lesen Sie die Zähler für die Gesamtwerte. Das einzelne whatsapp.sent-Event enthält kein recipient: Es ist die einmalige Übergabe an WhatsApp, die niemanden namentlich nennt. Die whatsapp.delivered- und whatsapp.read-Webhooks enthalten dasselbe Feld – so unterscheiden Sie ansonsten identische Callbacks.

4. Die Konversation einer Gruppe lesen

Übergeben Sie group_id an Nachrichten auflisten, um den Thread einer Gruppe in beiden Richtungen zu sehen:

for await (const msg of bird.whatsapp.list({ group_id: "wag_01krdgeqcxet5s7t44vh8rt9mg" })) {
  console.log(msg.id, msg.direction, msg.status);
}

for msg in client.whatsapp.list(group_id="wag_01krdgeqcxet5s7t44vh8rt9mg"):
    print(msg.id, msg.direction, msg.status)

for msg, err := range client.Whatsapp.List(context.Background(), bird.WhatsappListParams{
	GroupID: "wag_01krdgeqcxet5s7t44vh8rt9mg",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Direction, *msg.Status)
}

foreach ($bird->whatsapp->list(['group_id' => 'wag_01krdgeqcxet5s7t44vh8rt9mg']) as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird whatsapp list --group-id wag_01krdgeqcxet5s7t44vh8rt9mg

curl "https://us1.platform.bird.com/v1/whatsapp/messages?group_id=wag_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Eine eingehende Gruppennachricht enthält den Teilnehmer, der sie geschrieben hat, auf from und einen to, der sowohl Ihre Geschäftsnummer als auch group_id enthält: die Nummer, die sie empfangen hat, qualifiziert durch die Gruppe, über die sie eingegangen ist. Weder to noch from trifft auf eine Gruppe zu, daher ist group_id der einzige Filter, der die Liste auf eine Gruppe eingrenzt. Dieselben Nachrichten finden Sie im WhatsApp-Log im Dashboard.

Kosten

Ein Gruppenversand wird in den zwei Komponenten abgerechnet, die WhatsApp-Nachrichten senden beschreibt, mit je einem Unterschied in der Preisgestaltung. Die Gebühr von Bird wird einmal pro Versand berechnet und richtet sich nach dem Land der Geschäftsnummer, über die gesendet wurde, weil eine Gruppe mehrere Länder umfassen kann und kein einzelnes Empfängerland hat. Metas Anteil fällt pro Teilnehmer an, den die Nachricht erreicht hat, jeweils zum normalen Eins-zu-eins-Tarif für das Land des Teilnehmers. passthrough_amount wächst daher mit eintreffenden Bestätigungen. Ab dem 1. Oktober 2026 deckt dieser Anteil auch Freiform-Inhalte ab, die an die Gruppe gesendet werden. Meta berechnet diese pro erreichtem Teilnehmer und zieht sie von den 1.000 kostenlosen Service-Nachrichten pro Monat der sendenden Nummer ab: Preisänderungen Oktober 2026.

Fehlerbehebung

• 404 (E15046): Die Gruppen-ID benennt keine Gruppe, die dieser Workspace besitzt. Eine Gruppe gehört zum Workspace, der sie erstellt hat. Daher wird eine ID aus einem anderen Workspace hier nicht gefunden.
• 409 (E15047): Die Gruppe ist ausstehend, gesperrt, gelöscht oder fehlgeschlagen. Nur eine Gruppe im Status Active kann benachrichtigt werden, und eine Gruppe bleibt ausstehend, bis WhatsApp sie bestätigt.
• 422 (E15018): Lassen Sie from weg. Die Gruppe sendet über die Nummer, mit der sie erstellt wurde.
• 422 (E15052): Interaktiver Inhalt oder ein Authentifizierungs-Template. Siehe Was eine Gruppe akzeptiert.
• 422 (E15044): Das Service-Fenster der Gruppe ist geschlossen. Senden Sie ein Template oder warten Sie, bis ein Teilnehmer in die Gruppe schreibt.
• status bleibt auf sent stehen: Weniger als recipient_count Teilnehmer haben die Zustellung bestätigt. Lesen Sie die Events der Nachricht, um zu sehen, wer aussteht.

Nächste Schritte

• WhatsApp-Gruppennachrichten empfangen: Absender identifizieren und der Gruppe antworten
• WhatsApp-Gruppen verwalten: Teilnehmer, Einladungslinks und Beitrittsanfragen verwalten
• Webhooks für den Nachrichtenstatus: Zustellungsupdates für Ihre Nachrichten empfangen
• Geschäftsbezogene Benutzer-IDs: einen Teilnehmer identifizieren, dessen Telefonnummer Sie nicht haben