Verzenden naar een WhatsApp-groep

Een groepsverzending is een gewone POST /v1/whatsapp/messages waarvan to een groep noemt in plaats van een persoon: één request, één bericht, en elke deelnemer van die groepschat ontvangt het en kan antwoorden waar de anderen het zien. Wat verandert is de rapportage. Het bericht bevat tellers voor hoeveel deelnemers het heeft bereikt, en bezorging wordt per deelnemer bevestigd.

Een groep aanmaken en beheren staat los van het versturen van berichten. WhatsApp-groepen beheren behandelt het aanmaken via de API en het delen van de uitnodigingslink, en WhatsApp-groepen behandelt waarvoor een groep dient en welke limieten WhatsApp eraan stelt.

Vereisten

Je hebt een API-sleutel nodig met WhatsApp-schrijfrechten en het ID van een actieve groep (wag_…). Kopieer het van het tabblad Details van de groep op de pagina Groups, lees het uit to.group_id op een bericht dat via de groep binnenkwam, of bekijk je groepen.

Vervang het voorbeeld-groeps-ID door je eigen ID. Initialiseer de client voor je taal met de handleiding voor TypeScript, Python, Go of PHP SDK. Gebruik voor CLI-voorbeelden installeer en authenticeer de CLI met WhatsApp-schrijftoegang. Gebruik de API-host voor je werkruimteregio in cURL-requests.

1. Verstuur het bericht

Zet het groeps-ID in to en laat from weg. Een groep is gekoppeld aan het bedrijfsnummer waarmee hij is aangemaakt, dus dat nummer is het enige waarmee het bericht verstuurd kan worden; een afzender opgeven geeft een 422 E15018 terug.

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." }
    }'

De API retourneert 202 met de groep op to.group_id, status: accepted, en recipient_count: hoeveel mensen in de groep zaten toen de verzending werd geaccepteerd. Die telling is de noemer voor alles in stap 3, en ligt vast op dat moment. Iemand die via de uitnodigingslink deelneemt terwijl het bericht onderweg is, ontvangt het niet en wijzigt de telling niet.

2. Wat een groep accepteert

Een groep accepteert tekst, afbeeldingen, video, audio, stickers, documenten, een locatie, contactkaarten, en een template die je werkruimte heeft aangemaakt in elke categorie behalve authenticatie. Twee soorten content worden geweigerd met een 422 E15052, voordat het bericht wordt aangemaakt of in rekening gebracht, omdat WhatsApp geen van beide bezorgt in een groepschat:

• Alles wat interactief is: antwoordknoppen, lijstmenu's, linkknoppen, carrousels, en de locatie- en contactinformatieverzoeken.
• Een authenticatietemplate. Stuur de eenmalige verificatiecode in plaats daarvan rechtstreeks naar de deelnemer.

Een Bird-beheerde template wordt verstuurd vanaf een nummer van Bird, dat nooit het nummer is waaraan een groep is gekoppeld. Een template naar een groep sturen geeft daarom een 422 E15001 terug.

Vrije content vereist nog steeds een open klantenservicevenster, en een groep heeft er een eigen: elke deelnemer die een bericht naar de groep stuurt, opent één 24-uursvenster voor de hele groep, en diezelfde persoon die je buiten de groep een bericht stuurt, opent het niet. Zodra het venster verloopt, bereikt alleen een template de groep.

3. Volg de fan-out

Haal het bericht op om te zien hoe ver het is gekomen. Drie tellers rapporteren de fan-out:

Bij een groepsbericht rapporteert status het verste punt dat elke ontvanger heeft bereikt: het wordt pas delivered zodra delivered_count gelijk is aan recipient_count, en blijft sent zolang sommigen hebben bevestigd en anderen niet. Geen enkel WhatsApp-bericht heeft een read-status, dus lezen is read_count en read_at. delivered_at en read_at zijn van de eerste ontvanger, niet van de laatste. failed en rejected zijn nooit per deelnemer, omdat er één overdracht aan WhatsApp is en één manier waarop die kan worden geweigerd.

Een verzending naar een groep waar nog niemand lid van was bevat helemaal geen tellers, omdat er geen noemer te rapporteren is. Gebruik daarom to.group_id in plaats van de tellers om een groepsbericht van een een-op-eenbericht te onderscheiden.

Om te zien over welke deelnemer een bevestiging gaat, bekijk de events van het bericht. Een groepsverzending wordt uitgesplitst in maximaal één whatsapp.delivered en maximaal één whatsapp.read per deelnemer, elk met recipient met het telefoonnummer van die persoon, hun bedrijfsgebonden gebruikers-ID, of beide. Geen van beide is gegarandeerd: WhatsApp slaat het afleveringsbewijs over voor een deelnemer die al naar de chat kijkt, en een leesbevestiging komt alleen binnen als diegene het bericht opent. Tel wat binnenkomt in plaats van op één van elk per deelnemer te wachten, en lees de tellers voor de totalen. Het enkele whatsapp.sent-event bevat geen recipient: dat is de ene overdracht aan WhatsApp, die niemand bij naam noemt. De whatsapp.delivered- en whatsapp.read-webhooks bevatten hetzelfde veld, en zo onderscheid je verder identieke callbacks van elkaar.

4. Lees de conversatie van één groep

Geef group_id mee aan list messages voor de thread van één groep, in beide richtingen:

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"

Een inkomend groepsbericht wordt teruggegeven met de deelnemer die het schreef op from, en een to die zowel je bedrijfsnummer als group_id bevat: het nummer dat het ontving, gekwalificeerd door de groep waardoor het binnenkwam. Noch to noch from matcht een groep, dus group_id is het enige filter dat de lijst tot één groep beperkt. Dezelfde berichten staan in het WhatsApp-log in het dashboard.

Kosten

Een groepsverzending wordt in rekening gebracht in de twee componenten die WhatsApp-berichten versturen beschrijft, met één verschil in de prijsbepaling van elk. De vergoeding van Bird wordt eenmaal berekend voor de verzending en is gebaseerd op het land van het bedrijfsnummer waarmee het bericht is verstuurd, omdat een groep meerdere landen kan beslaan en geen enkel ontvangerland heeft. Het aandeel van Meta loopt op per deelnemer die het bericht heeft bereikt, elk geprijsd tegen het gewone een-op-eentarief voor het land van die deelnemer, dus passthrough_amount groeit naarmate hun ontvangstbewijzen binnenkomen. Vanaf 1 oktober 2026 dekt dat aandeel ook vrije content die naar de groep is gestuurd, die Meta per bereikte deelnemer in rekening brengt en afboekt van de 1.000 gratis serviceberichten per maand van het verzendnummer: prijswijzigingen oktober 2026.

Probleemoplossing

• 404 (E15046): Het groeps-ID verwijst naar geen enkele groep in deze werkruimte. Een groep behoort tot de werkruimte die hem heeft aangemaakt, dus een ID van een andere werkruimte wordt hier niet gevonden.
• 409 (E15047): De groep is in behandeling, opgeschort, verwijderd of mislukt. Alleen een Active-groep kan berichten ontvangen, en een groep blijft in behandeling totdat WhatsApp hem bevestigt.
• 422 (E15018): Laat from weg. De groep verstuurt via het nummer waarmee hij is aangemaakt.
• 422 (E15052): Interactieve content of een authenticatietemplate. Zie wat een groep accepteert.
• 422 (E15044): Het servicevenster van de groep is gesloten. Stuur een template, of wacht tot een deelnemer naar de groep schrijft.
• status blijft op sent staan: Minder dan recipient_count deelnemers hebben bezorging bevestigd. Bekijk de events van het bericht om te zien wie er nog openstaat.

Volgende stappen

• WhatsApp-groepsberichten ontvangen: de afzender identificeren en de groep beantwoorden
• WhatsApp-groepen beheren: deelnemers, uitnodigingslinks en deelnameverzoeken beheren
• Webhooks voor berichtstatus: bezorgingsupdates voor je berichten ontvangen
• Bedrijfsgebonden gebruikers-ID's: een deelnemer identificeren van wie je het telefoonnummer niet hebt