Receiving WhatsApp group messages

Anything a participant writes in a group arrives the way any other inbound WhatsApp message does: the same whatsapp.received event, the same content arms, the same media fetch. Two things are particular to a group. The message names both the participant who wrote it and the group it came through, and your reply goes to the group rather than to that person.

Receiving WhatsApp messages covers the parts that are not group-specific: every content arm, fetching inbound media, and quoted replies.

What a group message carries

An inbound group message reads back with two addresses rather than one:

from is the participant who wrote it, never the group. It carries their bsuid (business-scoped user ID), their phone_number when your business knows it, and their username and display_name when they publish a profile. A participant who has not shared their number with you is identified by the bsuid alone, which is enough to address them.
to carries your business number and the group. phone_number is the number that received the message, and group_id is the group it arrived through.

group_id appears on to and nowhere else, so its presence there is what tells a group message from a one-to-one one, in either direction. A group message carries no counters: recipient_count, delivered_count, and read_count report an outbound fan-out, and an inbound message has none.

To read one group's thread, both directions at once, filter the message list by group_id as Sending to a WhatsApp group shows.

Replying to the group

A participant writing in the group opens a single 24-hour customer service window for the whole group, not one per person. While it is open, free-form content reaches the group; once it lapses, a template does. Address the reply to the group, with the group ID in to and no from. See Sending to a WhatsApp group.

Writing to that participant privately is a separate conversation with its own window, and the group message does not open it. A free-form message addressed to their phone number or bsuid is refused with a 422 E15044 unless they have separately messaged your business in the last 24 hours. A template reaches them either way.

Acknowledging and reacting

Both acknowledgements work on a group message and take the same calls as they do on any other inbound message:

Mark it as read with the message's own ID. Nothing about the call changes for a group.
React to it with one emoji. The reaction goes to the group, so every participant sees it. A group that is not active refuses the change with a 409 E15047, which is the one refusal a reaction on a group message has that a one-to-one reaction does not.

The webhook

whatsapp.received carries a group message on the same envelope as any other, with the group on to:

Esempio di codice

{
  "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
  }
}

Read data.to.group_id to route the message to the group's thread, and data.from to attribute it to a participant. A subscriber that keys conversations on from alone folds every participant of a group into a separate thread and loses the group.

There is no event for the group itself. Someone joining or leaving, a name change, or a pin produces no webhook, so the Groups page is where a group's membership is read.

Next steps

Sending to a WhatsApp group: addressing the group, what it takes, and its per-participant receipts
WhatsApp groups: creating a group, invite links, and what WhatsApp limits
Receiving WhatsApp messages: every content arm, media, and quoted replies
Business-scoped user IDs: addressing a participant whose phone number you do not have

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione