Sign inGet Started
Jetzt starten
Anleitungen
API-Referenz
SDKs
CLI
Wissensdatenbank
Changelog

WhatsApp-Gruppen verwalten

Alles, was die Seite Groups bietet, decken auch zwölf Operationen unter /v1/whatsapp/groups ab. So bilden Sie den gesamten Lebenszyklus einer Gruppe im Code ab: erstellen, auf die Bestätigung durch WhatsApp warten, den Einladungslink verteilen, über den Beitritt entscheiden, Details und Pins aktuell halten und die Gruppe löschen, wenn die Konversation beendet ist.

Zwei Punkte prägen jeden Aufruf auf dieser Seite. Niemand kann einer Gruppe hinzugefügt werden – der Einladungslink ist der einzige Weg hinein, und die Einladung erfolgt außerhalb der API. Die meisten Änderungen werden bei WhatsApp wirksam, nicht in der Antwort – der Aufruf, der eine Änderung annimmt, ist nicht der Aufruf, der Ihnen das Ergebnis mitteilt; Wie eine Änderung wirksam wird behandelt das einmal für jede betroffene Operation.

WhatsApp-Gruppen erklärt, wofür eine Gruppe gedacht ist, und zeigt denselben Lebenszyklus im Dashboard. Nachricht an eine WhatsApp-Gruppe senden behandelt das Senden von Nachrichten.

Voraussetzungen

Sie benötigen einen API-Schlüssel mit whatsapp_management-Zugriff: Lese-Stufe für die Leseoperationen auf dieser Seite, Schreib-Stufe für alles andere. Users, teams, and roles behandelt die Vergabe.

Außerdem benötigen Sie eine Geschäftsnummer mit dem Status Official Business Account, den WhatsApp vom Administrator einer Gruppe verlangt und den Before you create a group behandelt. GET /v1/whatsapp/numbers gibt ihn pro Nummer als is_official_business_account aus – lesen Sie ihn dort ab, statt ihn über einen 412 zu ermitteln. Der Wert entspricht dem Stand beim meta_synced_at der Nummer, daher ist eine erst vor Minuten verbundene Nummer möglicherweise noch nicht zurückgelesen worden.

Initialisieren Sie den Client für Ihre Sprache mit der Anleitung für TypeScript, Python, Go oder PHP SDK. Für CLI-Beispiele: CLI installieren und authentifizieren. Die cURL-Beispiele verwenden den US-Host; wenn Ihr Schlüssel mit bk_eu1_ beginnt, rufen Sie stattdessen https://eu1.platform.bird.com auf. Die SDKs lesen die Region aus Ihrem Schlüssel und setzen daher keinen Host.

1. Gruppe erstellen

Beim Erstellen geben Sie die administrierende Nummer und einen Betreff an, sonst niemanden. Zwei Einstellungen gelten für die gesamte Lebensdauer der Gruppe und können danach nicht geändert werden: die Nummer und join_approval_mode. Letzteres legt fest, ob das Öffnen des Einladungslinks eine Person direkt aufnimmt (auto_approve, Standard) oder eine Beitrittsanfrage auslöst, über die Sie entscheiden (approval_required).

Note: creating a group needs a business number with Official Business Account status, the blue check mark WhatsApp puts next to a business name in the chat. WhatsApp Official Business Account covers what Meta requires and how to request it.

const group = await bird.whatsapp.groups.create({
  whatsapp_number_id: "wan_01krdgeqcxet5s7t44vh8rt9mg",
  subject: "Norwood Fleet — Tuesday route",
  join_approval_mode: "approval_required",
});
console.log(group.id, group.status); // pending; read it back for the invite link

Die API gibt 202 zurück, mit der Gruppe im Status status pending und ohne invite_link: WhatsApp stellt den Link erst bei der Bestätigung der Gruppe aus. Der Betreff kann bis zu 128 Zeichen lang sein und eine optionale description bis zu 2.048. Beides wird jedem angezeigt, der den Link öffnet – benennen Sie die Gruppe daher nach ihrem Zweck statt nach einer internen Referenz.

2. Auf die Bestätigung durch WhatsApp warten

Lesen Sie die Gruppe ab, bis ihr status den Status pending verlässt. Die Abfrage antwortet unabhängig vom Status mit 200, verzweigen Sie also anhand von status statt anhand des Aufruferfolgs.

const group = await bird.whatsapp.groups.get("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(group.status, group.invite_link);

Fünf Status können zurückkommen, und nur einer davon ist eine Gruppe, mit der Sie arbeiten können:

StatusBedeutung
pendingWhatsApp hat die Gruppe noch nicht bestätigt. invite_link ist null und nichts davon ist teilbar
activeDie Gruppe existiert, ihr Einladungslink funktioniert, und sie nimmt Nachrichten und Änderungen an
suspendedWhatsApp hat die Aktivität in der Gruppe gestoppt. Nur WhatsApp hebt das auf
deletedDie Gruppe ist weg und bleibt lesbar, damit eine gespeicherte Referenz weiterhin auflöst
failedWhatsApp hat die Erstellung abgelehnt, was endgültig ist

failed ist der andere Weg aus pending, und last_operation.last_error.description enthält den eigenen Grund von WhatsApp. Versuchen Sie niemals eine fehlgeschlagene Erstellung für dieselbe Gruppe erneut: Erstellen Sie stattdessen eine neue und ändern Sie, was die Ablehnung beanstandet hat.

3. Personen in die Gruppe aufnehmen

Senden Sie den invite_link der Gruppe an die Personen, die Sie aufnehmen möchten, über einen Kanal, der sie bereits erreicht. Keine Operation fügt einen Teilnehmer hinzu, daher ist der Link der einzige Weg hinein, und der Beitritt ist deren Entscheidung. Der Link gewährt jedem Zugang, der ihn besitzt – behandeln Sie ihn daher als das, was er ist: ein Credential. WhatsApp-Gruppen behandelt, wie weit Sie einen Link verbreiten sollten.

Bei einer auto_approve-Gruppe ist jeder, der den Link hat, sofort drin, und es gibt nichts zu entscheiden. Bei einer approval_required-Gruppe löst das Öffnen des Links eine Beitrittsanfrage aus. Listen Sie die wartenden Anfragen auf und entscheiden Sie sie in Batches von bis zu 50:

const waiting = [];
for await (const request of bird.whatsapp.groups.joinRequests.list(
  "wag_01krdgeqcxet5s7t44vh8rt9mg",
)) {
  waiting.push(request.id);
}
const result = await bird.whatsapp.groups.joinRequests.approve("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  join_request_ids: waiting.slice(0, 50),
});
console.log(result.decided.length, result.failed.length);

WhatsApp entscheidet jede Anfrage einzeln, daher ist ein Batch teilweise anwendbar: Die Antwort trennt decided von failed, und jeder Fehler enthält den Grund von WhatsApp in error.description. Lesen Sie die Antwort statt des Statuscodes. Eine Ablehnung betrifft oft eine Person, die die aktuellen Nutzungsbedingungen von WhatsApp nicht akzeptiert hat – das lässt sich durch erneutes Versuchen nicht beheben.

Wenn Sie mehr Personen genehmigen, als die Gruppe Platz hat, wird der Aufruf nicht abgelehnt: Die passenden Anfragen werden entschieden, die restlichen kommen in failed zurück, jeweils mit dem Hinweis, dass die Genehmigung das Teilnehmerlimit der Gruppe überschreiten würde. Das Ablehnen funktioniert genauso, über POST /v1/whatsapp/groups/{group_id}/join-requests/batch-reject. Eine Anfrage verlässt die Liste auch, wenn die Person sie selbst zurückzieht, sodass eine eben noch gültige ID zum Zeitpunkt der Verwendung einen 422-E15051 zurückgeben kann.

Die 50 ist die eigene Grenze von Bird pro Anfrage, keine Grenze von WhatsApp. Ein Ablehnungsdurchlauf ist daher nicht daran gebunden, wie viele Personen die Gruppe aufnehmen kann.

Anfragen bei Eingang beobachten

Abonnieren Sie whatsapp.group.join_request_created und whatsapp.group.join_request_revoked, um zu erfahren, wann jemand einen Beitritt beantragt und wann er abbricht, statt die Liste abzufragen. Eine Anfrage, die zwischen zwei Abfragen der Liste erstellt und abgebrochen wird, hinterlässt keine Spur – diese Events sind der einzige Weg, sie zu sehen. Jedes Event enthält die join_request.id, die die Batch-Operationen erwarten, sodass Sie direkt daraus entscheiden können. WhatsApp-Gruppen-Webhooks zeigt beide Payloads und jedes Feld.

Beim Rotieren wird ein neuer Link ausgestellt und jeder vorherige Link der Gruppe ungültig, sodass niemand, der noch einen alten besitzt, beitreten kann. Rotieren Sie, wenn ein Link weiter verbreitet wurde als beabsichtigt, oder nachdem Sie jemanden entfernt haben, den Sie nicht zurückhaben möchten. Der neue Link kommt direkt im Aufruf zurück, der mit 200 antwortet:

const link = await bird.whatsapp.groups.inviteLink.rotate("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(link.invite_link); // every earlier link has stopped working

Rotieren ist nicht die Methode, um den aktuellen Link abzufragen. Die Gruppe enthält ihren invite_link, daher ist das Lesen der Gruppe die Abfrage.

Die CLI fragt nie nach, daher erfordern destruktive Befehle stattdessen --yes: Das Rotieren eines Links, das Entfernen eines Teilnehmers, das Löschen einer Gruppe, das Lösen eines Pins und das Ablehnen von Beitrittsanfragen werden ohne diesen Parameter mit confirmation_required abgelehnt.

Wie eine Änderung wirksam wird

WhatsApp bestätigt manche Änderungen in der Antwort und andere per Webhook, und der Statuscode zeigt an, welche Art Sie gerade sehen:

OperationAntwortWo das Ergebnis landet
Erstellen, aktualisieren, löschen202Der last_operation der Gruppe, sobald WhatsApp zurückmeldet
Teilnehmer entfernen202Der eigene last_operation des Teilnehmers in participants
Beitrittsanfragen genehmigen oder ablehnen202decided und failed direkt in der Antwort
Rotieren, pinnen, lösen200Die Antwort, die die bereits angewandte Änderung enthält

In den ersten beiden Zeilen bedeutet 202, dass die Anfrage angenommen, aber nicht angewandt wurde. last_operation.status steht auf pending, bis WhatsApp zurückmeldet – in der Regel innerhalb von Sekunden – und wechselt dann zu success oder failed, wobei last_error.description bei einem Fehler den Grund enthält. Lesen Sie die Gruppe erneut, um zu sehen, was wirksam wurde.

Solange eine Operation pending ist, gibt eine weitere Änderung am selben Objekt einen 409-E15054 zurück. Änderungen auf Gruppenebene teilen sich den last_operation der Gruppe, sodass eine ausstehende Umbenennung ein Löschen blockiert. Jeder Teilnehmer hat seinen eigenen, sodass das gleichzeitige Entfernen mehrerer Personen jeder Person ihren eigenen Status und ihren eigenen Fehler zuweist, und nur die ausstehende Entfernung dieser Person einen erneuten Versuch blockiert.

Zwei 409s schützen die Schreiboperationen, und status wird zuerst geprüft. Eine Gruppe, die nicht active ist, gibt daher E15047 zurück, unabhängig davon, was last_operation sagt. Das ist relevant für eine Gruppe, die noch erstellt wird und in beiden Hinsichten gleichzeitig ausstehend ist.

Jeder Schreibvorgang erwartet außerdem einen Idempotency-Key-Header. Idempotency behandelt sicheres erneutes Versuchen.

Betreff, Beschreibung oder Bild der Gruppe ändern

Ein Update ändert, was Teilnehmer oben in der Gruppe sehen. Felder, die Sie weglassen, bleiben unverändert. Senden Sie null, um die Beschreibung oder das Bild zu löschen, da ein leerer String ein 422 ist und kein zweiter Weg zum Löschen.

const group = await bird.whatsapp.groups.update("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  subject: "Norwood Fleet — Wednesday route",
});
console.log(group.last_operation?.status); // pending until WhatsApp reports back

WhatsApp wendet jedes Feld einzeln an, daher kann ein Update teilweise angewandt werden: ein Feld wird abgelehnt, während die anderen wirksam werden. Wenn die Operation abgeschlossen ist, enthält last_operation.results einen Eintrag pro Feld, das das Update gesendet hat – so können Sie eine Ablehnung der zugehörigen Eingabe zuordnen.

profile_picture_url benennt eine Datei in der Medienbibliothek Ihres Workspace statt einer beliebigen Internetadresse, und WhatsApp erwartet ein quadratisches JPEG mit mindestens 192 × 192 Pixeln und maximal 5 MB. Das Löschen entfernt das Bild, das Bird speichert, aber WhatsApp bietet keine Operation, um das Gruppenfoto zu entfernen – Teilnehmer sehen das aktuelle Bild weiterhin, bis ein neues es ersetzt. Die administrierende Nummer und join_approval_mode werden beim Erstellen festgelegt und können hier nicht geändert werden.

Teilnehmer entfernen

Das Entfernen kann nicht rückgängig gemacht werden. WhatsApp blockiert eine entfernte Person daran, der Gruppe über den Einladungslink wieder beizutreten, und die Sperre folgt der Person, nicht dem Link – das Rotieren des Links lässt sie daher nicht zurück. Da es keine Hinzufügen-Operation als Gegenstück gibt, kann niemand in diese Gruppe zurückkehren, sobald er entfernt wurde. Um die Person erneut zu erreichen, erstellen Sie eine neue Gruppe und laden Sie sie dorthin ein.

Benennen Sie die Person anhand eines der beiden Bezeichner, unter denen participants der Gruppe sie aufführt: ihre bsuid, die jeder hat, oder ihre phone_number im E.164-Format, die nur vorhanden ist, wenn WhatsApp sie teilt. Codieren Sie in einer URL das führende + als %2B, sofern Ihr Client das nicht automatisch tut.

const group = await bird.whatsapp.groups.participants.remove(
  "wag_01krdgeqcxet5s7t44vh8rt9mg",
  "+15550002222",
);
console.log(group.participants?.length);

Die Entfernung eines Teilnehmers steht auf pending in dessen eigenem Eintrag, bis WhatsApp sie bestätigt, und erreicht nie success: Das Verschwinden des Eintrags aus participants zeigt an, dass es funktioniert hat. Ein Wert, der jemanden benennt, der nicht in der Gruppe ist, gibt einen 422-E15050 zurück.

Nachricht pinnen

Beim Pinnen wird eine der eigenen Nachrichten der Gruppe oben im Chat fixiert, sodass jemand, der später beitritt, nicht nach dem Inhalt scrollen muss, auf den die Konversation immer wieder zurückkommt. Ein Pin gilt für duration_days, von 1 bis 30, und ist standardmäßig 7.

const pin = await bird.whatsapp.groups.pins.create("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  message_id: "wam_01kya19eknftrs2s6p82asmvnh",
  duration_days: 14,
});
console.log(pin.pinned_until);

Die Nachricht muss aus dieser Gruppe stammen: Eine Nachricht aus einer anderen Gruppe oder eine Einzelnachricht gibt einen 422-E15053 zurück. Eine Gruppe kann nur eine begrenzte Anzahl Pins gleichzeitig haben, und ein weiterer Pin darüber hinaus löst den ältesten, statt fehlzuschlagen. Das Pinnen einer bereits gepinnten Nachricht ersetzt deren Ablauf. Die aktuell gepinnten Nachrichten der Gruppe stehen in der Gruppe selbst als pinned_messages.

WhatsApp löst einen Pin automatisch, sobald die Tage abgelaufen sind – lösen Sie ihn also nur, um ihn vorzeitig zu entfernen. DELETE /v1/whatsapp/groups/{group_id}/pinned-messages/{message_id} antwortet mit 200, und das Wiederholen ist sicher: Eine Nachricht aus dieser Gruppe, die nicht gepinnt ist, ändert nichts und antwortet trotzdem mit 200.

Gruppe löschen

Das Löschen entfernt die Gruppe bei WhatsApp. Jeder Teilnehmer verliert den Zugang, Ihr Unternehmen eingeschlossen, und der Einladungslink funktioniert nicht mehr. Das kann nicht rückgängig gemacht werden, und um die Konversation erneut zu führen, müssen Sie eine neue Gruppe erstellen und deren Link versenden.

const group = await bird.whatsapp.groups.delete("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(group.last_operation?.status); // pending until WhatsApp confirms it

Die Gruppe bleibt danach unter status deleted lesbar, sodass eine gespeicherte Referenz weiterhin auflöst, statt zu einem 404 zu werden. Eine failed-Gruppe kann ebenfalls gelöscht werden, und diese erreicht kein externes System: Die Erstellung hat nie eine Gruppe bei WhatsApp erzeugt, daher ist das Entfernen des Eintrags Bird-eigene Buchführung. Jeder andere Status wird mit einem 409-E15047 abgelehnt.

Ihre Gruppen auflisten

Die Liste gibt die von Ihrem Workspace erstellten Gruppen zurück, neueste zuerst, als Cursor-Seite. Filtern Sie nach der administrierenden Nummer (number, als E.164-Nummer oder wan_-ID), nach dem WhatsApp Business Account, unter dem sie sendet (waba), oder nach status, wobei Sie den Parameter wiederholen können, um mehrere zu erfassen. q durchsucht Betreff und Beschreibung nach einem Teilstring, ohne Beachtung der Groß-/Kleinschreibung.

for await (const group of bird.whatsapp.groups.list({ status: ["active"] })) {
  console.log(group.id, group.subject, group.participant_count);
}

Eine gelöschte Gruppe bleibt mit status deleted in der Liste. Filtern Sie nach Status, um nur die Gruppen zu sehen, an die Sie noch Nachrichten senden können.

Fehlerbehebung

  • 412 (E15045): Die Nummer hat keinen Official-Business-Account-Status, daher lässt WhatsApp sie keine Gruppe erstellen. Die Entscheidung liegt bei WhatsApp: Beantragen Sie den Status im WhatsApp Manager im Profil der Nummer, oder erstellen Sie die Gruppe mit einer Nummer, die den Status bereits hat.
  • 404 (E15046): Die 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 aktive Gruppe nimmt Änderungen an. Lesen Sie die Gruppe ab, um ihren Status zu sehen.
  • 409 (E15049): Die Nummer administriert bereits die von WhatsApp erlaubten 10.000 Gruppen. Löschen Sie Gruppen, deren Konversation beendet ist, oder erstellen Sie diese auf einer anderen Nummer.
  • 409 (E15054): Eine Änderung an derselben Gruppe oder demselben Teilnehmer steht noch aus. Lesen Sie last_operation und warten Sie, bis sie abgeschlossen ist.
  • 422 (E15050): Der Pfad benennt niemanden in der Gruppe. Lesen Sie participants der Gruppe und verwenden Sie eine bsuid oder phone_number, wie dort angegeben.
  • 422 (E15051): Eine der Beitrittsanfrage-IDs wartet nicht mehr auf eine Entscheidung. Listen Sie die Anfragen erneut auf und verwenden Sie die zurückgegebenen IDs.
  • 422 (E15053): Die Nachricht gehört zu einer anderen Gruppe oder zu einer Einzelkonversation. Das Feld to.group_id der Nachricht gibt an, welche Gruppe sie pinnen kann.
  • Eine pending-Gruppe, die nie aktiv wird: Bird gibt das Warten auf, statt die Gruppe ausstehend zu belassen, und verschiebt sie nach failed mit dem Grund in last_operation.last_error. Erstellen Sie einen Ersatz, statt es erneut zu versuchen.

Referenz

Die vollständigen Request- und Response-Strukturen finden Sie in der API-Referenz: Erstellen, Auflisten, Abrufen, Aktualisieren, Löschen, Einladungslink rotieren, Teilnehmer entfernen, Auflisten, Genehmigen und Ablehnen von Beitrittsanfragen sowie Pinnen und Lösen einer Nachricht.

Nächste Schritte

Verwandte Ressourcen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Übung ausprobieren und ein Implementierungs-Briefing erhalten