Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

WhatsApp-groepen beheren

Alles wat de pagina Groups doet, doen twaalf bewerkingen onder /v1/whatsapp/groups ook, dus de hele levenscyclus van een groep past in code: aanmaken, wachten tot WhatsApp de groep bevestigt, de uitnodigingslink delen, bepalen wie er binnenkomt, de gegevens en pins actueel houden, en de groep verwijderen als het gesprek voorbij is.

Twee dingen bepalen elke aanroep op deze pagina. Niemand kan aan een groep worden toegevoegd, dus de uitnodigingslink is de enige manier om erin te komen, en mensen uitnodigen gebeurt buiten de API. De meeste wijzigingen worden bij WhatsApp verwerkt in plaats van in het antwoord, dus de aanroep die een wijziging accepteert is niet de aanroep die je vertelt dat het gelukt is; Hoe een wijziging wordt verwerkt behandelt dat één keer voor elke bewerking waarvoor het geldt.

WhatsApp-groepen behandelt waarvoor een groep dient en dezelfde levenscyclus in het dashboard. Verzenden naar een WhatsApp-groep behandelt het versturen van berichten.

Vereisten

Je hebt een API-sleutel nodig met whatsapp_management-toegang: leesniveau voor de reads op deze pagina, schrijfniveau voor al het andere. Users, teams, and roles behandelt hoe je dit toekent.

Je hebt ook een zakelijk nummer nodig met Official Business Account-status, die WhatsApp vereist van de beheerder van een groep en die Before you create a group behandelt. GET /v1/whatsapp/numbers rapporteert dit per nummer als is_official_business_account, dus lees het daar in plaats van het te ontdekken via een 412. De vlag is van het moment van de meta_synced_at van het nummer, dus een nummer dat enkele minuten geleden is verbonden, is mogelijk nog niet teruggelezen.

Initialiseer de client voor je programmeertaal met de TypeScript-, Python-, Go- of PHP-handleiding voor SDK. Voor CLI-voorbeelden: installeer en authenticeer de CLI. De cURL-voorbeelden gebruiken de US-host; als je sleutel begint met bk_eu1_, roep dan https://eu1.platform.bird.com aan. De SDK's lezen de regio uit je sleutel en stellen dus geen host in.

1. Maak de groep aan

Een create benoemt het beherende nummer en een onderwerp, en verder niemand. Twee keuzes liggen vast voor de hele levensduur van de groep en zijn achteraf niet meer te wijzigen: het nummer, en join_approval_mode, dat bepaalt of het openen van de uitnodigingslink iemand direct toelaat (auto_approve, de standaard) of een verzoek oplevert dat je zelf beslist (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

De API retourneert 202 met de groep op status pending en zonder invite_link: WhatsApp geeft de link uit wanneer het de groep bevestigt. Het onderwerp mag maximaal 128 tekens bevatten en een optionele description maximaal 2.048. Beide zijn zichtbaar voor iedereen die de link opent, dus geef de groep een naam die past bij het doel en niet bij een interne referentie.

2. Wacht tot WhatsApp de groep bevestigt

Lees de groep terug totdat de status niet meer pending is. De read antwoordt altijd met 200, ongeacht de status, dus vertак op status in plaats van op het slagen van de aanroep.

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

Er zijn vijf statussen mogelijk, en slechts één daarvan is een groep waarmee je kunt werken:

StatusWat het betekent
pendingWhatsApp heeft de groep niet bevestigd. invite_link is null en niets hiervan is deelbaar
activeDe groep bestaat, de uitnodigingslink werkt, en de groep accepteert berichten en wijzigingen
suspendedWhatsApp heeft de activiteit in de groep stopgezet. Alleen WhatsApp heft dit op
deletedDe groep is weg en blijft leesbaar, zodat een opgeslagen verwijzing ernaar nog steeds werkt
failedWhatsApp heeft de aanmaak geweigerd, en dat is definitief

failed is de andere uitweg uit pending, en last_operation.last_error.description bevat de eigen reden van WhatsApp. Probeer een mislukte aanmaak nooit opnieuw voor die groep: maak in plaats daarvan een nieuwe aan en pas aan waar de weigering bezwaar tegen maakte.

3. Laat mensen toe tot de groep

Stuur de invite_link van de groep naar de mensen die je erin wilt hebben, via welk kanaal hen al bereikt. Geen enkele operatie voegt een deelnemer toe, dus de link is de enige manier om binnen te komen en deelnemen is hun eigen keuze. De link geeft toegang aan iedereen die hem heeft, dus behandel hem als de credential die het is: WhatsApp groups beschrijft hoe ver je er een kunt verspreiden.

Bij een auto_approve-groep is iedereen met de link meteen lid en valt er niets te beslissen. Bij een approval_required-groep levert het openen van de link een deelnameverzoek op. Bekijk de wachtende verzoeken en beslis ze in batches van maximaal 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 beslist elk verzoek afzonderlijk, dus een batch is gedeeltelijk toepasbaar: het antwoord scheidt decided van failed, en elke fout bevat de reden die WhatsApp gaf in error.description. Lees het antwoord in plaats van de statuscode. Een weigering is vaak een persoon die de huidige voorwaarden van WhatsApp niet heeft geaccepteerd, en dat lost opnieuw proberen niet op.

Meer mensen goedkeuren dan waar de groep plek voor heeft, weigert de aanroep niet: de verzoeken die passen worden beslist en de rest komt terug in failed, elk met de melding dat de goedkeuring de groep voorbij de deelnemerslimiet zou brengen. Afwijzen werkt op dezelfde manier, via POST /v1/whatsapp/groups/{group_id}/join-requests/batch-reject. Een verzoek verdwijnt ook uit de lijst wanneer de persoon het zelf intrekt, dus een ID dat een moment geleden geldig was kan tegen de tijd dat je het gebruikt een 422 E15051 opleveren.

De 50 is de eigen limiet van Bird op één verzoek, niet die van WhatsApp, dus een afwijzingsronde is niet beperkt tot het aantal mensen dat de groep kan bevatten.

Verzoeken volgen zodra ze binnenkomen

Abonneer je op whatsapp.group.join_request_created en whatsapp.group.join_request_revoked om te weten wanneer iemand wil deelnemen en wanneer diegene annuleert, in plaats van de lijst te pollen. Een verzoek dat tussen twee reads van de lijst wordt ingediend en geannuleerd, laat niets achter, dus deze events zijn de enige manier om het te zien. Elk event bevat de join_request.id die de batchbewerkingen verwachten, zodat je er direct vanuit kunt beslissen. WhatsApp-groepwebhooks bevat beide payloads en elk veld.

Roteren geeft een nieuwe link uit en stopt elke link die de groep eerder had, zodat iemand die er nog een heeft niet meer kan deelnemen. Roteer wanneer een link verder is verspreid dan je bedoelde, of nadat je iemand hebt verwijderd die je niet terug wilt. De nieuwe link komt terug op de aanroep zelf, die 200 antwoordt:

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

Roteren is niet hoe je de huidige link leest. De groep bevat zijn invite_link, dus de groep lezen is de read.

De CLI vraagt nooit om bevestiging, dus zijn destructieve commando's vereisen in plaats daarvan --yes: een link roteren, een deelnemer verwijderen, een groep verwijderen, een bericht lospinnen en deelnameverzoeken afwijzen weigeren allemaal met confirmation_required zonder dat veld.

Hoe een wijziging wordt doorgevoerd

WhatsApp bevestigt sommige wijzigingen in zijn antwoord en andere via een webhook, en de statuscode geeft aan welk type je ziet:

BewerkingAntwoordtWaar het resultaat terechtkomt
Aanmaken, bijwerken, verwijderen202De last_operation van de groep, zodra WhatsApp terugrapporteert
Een deelnemer verwijderen202De eigen last_operation van die deelnemer in participants
Deelnameverzoeken goedkeuren of afwijzen202decided en failed op het antwoord zelf
Roteren, pinnen, lospinnen200Het antwoord, wat de al doorgevoerde wijziging is

Voor de eerste twee rijen is de 202 het geaccepteerde verzoek, niet het doorgevoerde. last_operation.status is pending totdat WhatsApp terugrapporteert, meestal binnen seconden, en wordt dan success of failed, waarbij last_error.description bij een fout de reden bevat. Lees de groep opnieuw om te zien wat is doorgevoerd.

Zolang een bewerking pending is, retourneert een andere wijziging aan hetzelfde ding een 409 E15054. Wijzigingen op groepsniveau delen de last_operation van de groep, dus een openstaande hernoeming blokkeert een verwijdering. Elke deelnemer heeft een eigen status, dus als je meerdere mensen tegelijk verwijdert, krijgt ieder een eigen status en een eigen fout, en alleen de openstaande verwijdering van die persoon blokkeert een nieuwe poging bij diegene.

Twee 409's bewaken de schrijfbewerkingen en status wordt eerst gecontroleerd, dus een groep die niet active is retourneert E15047 ongeacht wat zijn last_operation zegt. Dat is van belang voor een groep die nog wordt aangemaakt, die op beide punten tegelijk pending is.

Elke schrijfbewerking vereist ook een Idempotency-Key-header. Idempotency behandelt veilig opnieuw proberen.

Het onderwerp, de beschrijving of de afbeelding van de groep wijzigen

Een update wijzigt wat deelnemers bovenaan de groep zien. Velden die je weglaat blijven ongewijzigd; stuur null om de beschrijving of de afbeelding te wissen, want een lege string is een 422 in plaats van een tweede manier om te wissen.

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 past elk veld apart toe, dus een update kan gedeeltelijk worden doorgevoerd: één veld geweigerd terwijl de andere doorgang vinden. Wanneer de bewerking is afgerond, bevat last_operation.results één vermelding per veld dat de update meestuurde, waarmee je een weigering naast de invoer kunt plaatsen waar die bij hoort.

profile_picture_url verwijst naar een bestand in de mediabibliotheek van je werkruimte, niet naar een adres op het internet, en WhatsApp accepteert een vierkante JPEG van minimaal 192 bij 192 pixels en maximaal 5 MB. Wissen verwijdert de afbeelding die Bird opslaat, maar WhatsApp heeft geen bewerking om de foto van een groep te verwijderen, dus deelnemers blijven de huidige zien totdat een andere afbeelding deze vervangt. Het beherende nummer en join_approval_mode worden vastgelegd bij het aanmaken en kunnen hier niet worden gewijzigd.

Een deelnemer verwijderen

Verwijdering kan niet ongedaan worden gemaakt. WhatsApp blokkeert een verwijderde persoon voor deelname aan de groep via de uitnodigingslink, en de blokkering volgt de persoon in plaats van de link, dus de link roteren laat diegene niet opnieuw toe. Zonder een toevoegbewerking als tegenhanger retourneert niets iemand naar deze groep zodra diegene eruit is, en opnieuw contact opnemen betekent een andere groep aanmaken en diegene daarvoor uitnodigen.

Benoem de persoon met een van de twee identifiers waaronder de participants van de groep hen vermelden: hun bsuid, die iedereen heeft, of hun phone_number in E.164-formaat, dat er alleen is wanneer WhatsApp het deelt. Percent-encode in een URL de voorloop-+ als %2B, tenzij je client dat voor je doet.

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

De verwijdering van een deelnemer is pending op hun eigen vermelding totdat WhatsApp het bevestigt, en bereikt nooit success: het verdwijnen van de vermelding uit participants geeft aan dat het is gelukt. Een waarde die iemand benoemt die niet in de groep zit, retourneert een 422 E15050.

Een bericht pinnen

Pinnen houdt een van de eigen berichten van de groep bovenaan de chat, zodat iemand die later deelneemt niet hoeft te scrollen naar waar het gesprek steeds op terugkomt. Een pin duurt duration_days, van 1 tot 30, en is standaard 7.

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

Het bericht moet er een zijn dat deze groep bevat: een bericht in een andere groep, of een één-op-éénbericht, retourneert een 422 E15053. Een groep kan maar een beperkt aantal pins tegelijk bevatten, en voorbij dat aantal pinnen maakt de oudste los in plaats van te falen; een al gepind bericht opnieuw pinnen vervangt de vervaldatum. Wat de groep momenteel pint staat op de groep zelf, als pinned_messages.

WhatsApp maakt een bericht vanzelf los zodra de dagen zijn verstreken, dus pin alleen los om er een voortijdig af te halen. DELETE /v1/whatsapp/groups/{group_id}/pinned-messages/{message_id} antwoordt 200, en herhalen is veilig: een bericht dat deze groep bevat maar niet gepind is, verandert niets en antwoordt nog steeds 200.

De groep verwijderen

Verwijderen verwijdert de groep bij WhatsApp. Elke deelnemer verliest toegang, inclusief je eigen bedrijf, en de uitnodigingslink stopt met werken. Dit kan niet ongedaan worden gemaakt, en het gesprek opnieuw voeren betekent een nieuwe groep aanmaken en de link ervan versturen.

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

De groep blijft daarna leesbaar op status deleted, zodat een opgeslagen verwijzing ernaar nog steeds resolvt in plaats van een 404 te worden. Een failed-groep kan ook worden verwijderd, en die bereikt geen extern systeem: het aanmaken heeft nooit een groep geproduceerd bij WhatsApp, dus het opschonen van de rij is de eigen boekhouding van Bird. Elke andere status weigert met een 409 E15047.

Je groepen weergeven

De lijst retourneert de groepen die je werkruimte heeft aangemaakt, nieuwste eerst, als een cursorpagina. Filter op het beherende nummer (number, als E.164-nummer of wan_-ID), op het WhatsApp Business Account waaronder het verstuurt (waba), of op status, waarbij je de parameter herhaalt om op meerdere te matchen. q doorzoekt het onderwerp en de beschrijving op een substring, hoofdletterongevoelig.

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

Een verwijderde groep blijft in de lijst staan met status deleted, dus filter op status om alleen de groepen te zien waarnaar je nog berichten kunt sturen.

Probleemoplossing

  • 412 (E15045): Het nummer heeft geen Official Business Account-status, dus WhatsApp laat het geen groep aanmaken. De beslissing is van WhatsApp: vraag de status aan in WhatsApp Manager op het profiel van het nummer, of maak de groep aan op een nummer dat de status al heeft.
  • 404 (E15046): Het ID verwijst naar geen groep die deze werkruimte bevat. Een groep behoort tot de werkruimte die hem heeft aangemaakt, dus een ID uit een andere werkruimte wordt hier niet gevonden.
  • 409 (E15047): De groep is pending, opgeschort, verwijderd of gefaald. Alleen een actieve groep accepteert een wijziging. Lees de groep om te zien waar die staat.
  • 409 (E15049): Het nummer beheert al de 10.000 groepen die WhatsApp toestaat. Verwijder groepen waarvan het gesprek is afgelopen, of maak deze op een ander nummer aan.
  • 409 (E15054): Een wijziging aan dezelfde groep of dezelfde deelnemer is nog niet afgerond. Lees last_operation en wacht tot deze is doorgevoerd.
  • 422 (E15050): Het pad verwijst naar niemand in de groep. Lees de participants van de groep en gebruik een bsuid of phone_number zoals die worden gerapporteerd.
  • 422 (E15051): Een van de deelnameverzoek-ID's wacht niet meer op een beslissing. Haal de verzoeken opnieuw op en gebruik de ID's die terugkomen.
  • 422 (E15053): Het bericht behoort tot een andere groep of tot een één-op-éénconversatie. De to.group_id van een bericht geeft aan welke groep het kan pinnen.
  • Een pending-groep die nooit actief wordt: Bird stopt met wachten in plaats van de groep pending te laten, en verplaatst de groep naar failed met de reden op last_operation.last_error. Maak een vervanging aan in plaats van opnieuw te proberen.

Referentie

De volledige request- en responseschema's staan in de API-referentie: aanmaken, weergeven, ophalen, bijwerken, verwijderen, de uitnodigingslink roteren, een deelnemer verwijderen, deelnameverzoeken weergeven, goedkeuren en afwijzen, en een bericht pinnen en lospinnen.

Volgende stappen

Gerelateerde bronnen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Probeer de oefening en ontvang een implementatieoverzicht