Group messaging
Updated: Nov 4, 2026
Copy for LLM
This page now only discusses how to send and receive messages in groups.
To learn how to manage groups, see the Group Management Reference page
Groups now support marking messages as read. Use the Messages API to mark individual group messages as read and display read receipts. Learn how to mark group messages as read.
Overview
This document describes the APIs and webhooks for sending and receiving messages within groups. It details support for various message types, including:
- Text messages
- Media messages
- Text-based templates
- Media-based templates
Subscribe to groups metadata webhooks
To receive webhook notifications for metadata about your groups, subscribe to the following webhook fields:
group_lifecycle_updategroup_participants_updategroup_settings_updategroup_status_update
For a full reference of webhooks for the Groups API, see the Webhooks for Groups API reference.
Send group message
To send a group message, use the Messages API.
This endpoint has been extended to support group messages in the following way:
- The
recipient_typefield now supportsgroupas well asindividual. - The
tofield now supports thegroup IDthat is obtained when using the Groups API.
Example group message send
curl 'https://graph.facebook.com/v27.0/756079150920219/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAAu...' \
-d '
{
"messaging_product": "whatsapp",
"recipient_type": "group",
"to": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD",
"type": "text",
"text": {
"preview_url": true,
"body": "This is another destination option: https://www.luckytravel.com/DDLmU5F1Pw"
}
}'
Webhooks
Group message sent example
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID>", "recipient_id": "<GROUP_ID>", "recipient_type": "group", "status": "sent", "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>", } ] }, "field": "messages" } ] } ] }
Group message failed example
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "statuses": [ { "id": "<WHATSAPP_MESSAGE_ID>", "recipient_id": "<GROUP_ID>", "recipient_type": "group", "status": "failed", "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>", "errors": [ { "code": "<ERROR_CODE>", "title": "<ERROR_TITLE>", "message": "<ERROR_MESSAGE>", "error_data": { "details": "<ERROR_DETAILS>", }, "href": "/documentation/business-messaging/whatsapp/support/error-codes" } ] } ] }, "field": "messages" } ] } ] }
Receive group messages
You can use the following webhooks to receive statuses on messages received in the group.
The
message object includes a group_id field to indicate this is a group message. The from field in the message object and the contact object point to the same participant who sends this message.Use
user_id and from_user_id to identify the participant who sent the message. wa_id and from are omitted when the user has adopted a username and their phone number is unavailable. See Business-scoped user IDs and the group messages webhook reference.Webhooks
Receive group message webhook sample
{ "object": "whatsapp_business_account", "entry": [{ "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [{ "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>" }, "contacts": [{ "profile": { "name": "<WHATSAPP_USER_NAME>", "username": "<USERNAME>" <!-- only included if user has adopted a username --> }, "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>", <!-- omitted if user's phone number is unavailable --> "user_id": "<BSUID>", "parent_user_id": "<PARENT_BSUID>" <!-- only included if parent BSUIDs enabled --> }], "messages": [{ "from": "<GROUP_PARTICIPANT_PHONE_NUMBER>", <!-- omitted if user's phone number is unavailable --> "from_user_id": "<BSUID>", "from_parent_user_id": "<PARENT_BSUID>", <!-- only included if parent BSUIDs enabled --> "group_id": "<GROUP_ID>", "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>", "text": { "body": "<MESSAGE_BODY>" }, "type": "text" }] }, "field": "messages" }] }] }
Receive unsupported group message webhook sample
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>", "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>", }, "contacts": [ { "profile": { "name": "<WHATSAPP_USER_NAME>", "username": "<USERNAME>" <!-- only included if user has adopted a username --> }, "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>", <!-- omitted if user's phone number is unavailable --> "user_id": "<BSUID>", "parent_user_id": "<PARENT_BSUID>" <!-- only included if parent BSUIDs enabled --> } ], "messages": [ { "from": "<GROUP_PARTICIPANT_PHONE_NUMBER>", <!-- omitted if user's phone number is unavailable --> "from_user_id": "<BSUID>", "from_parent_user_id": "<PARENT_BSUID>", <!-- only included if parent BSUIDs enabled --> "group_id": "<GROUP_ID>", "id": "<WHATSAPP_MESSAGE_ID>", "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>", "errors": [ { "code": 130501, "message": "Message type is not currently supported", "title": "Unsupported message type", "error_data": { "details": "<ERROR_DETAILS>" } } ], "type": "unsupported" } ] }, "field": "messages" } ] } ] }
Pin and unpin group message
Pinning a message highlights its relevance.
The display order of the pinned messages is based on the chronological order of parent messages, newest first. If three messages are already pinned when a new pin request is made, the oldest pinned message will be automatically unpinned.
Limits
- When calling the API, only one message can be pinned at a time.
- Only the group admin can pin or unpin messages.
- A maximum of 3 pinned messages can exist at any time.
Request syntax
POST /<BUSINESS_PHONE_NUMBER_ID>/messagesNote: You will receive an error in the sync response if the
recipient_type and to type do not match.Request body
{ "messaging_product": "whatsapp", "recipient_type": "group", "to": "<GROUP_ID>", "type": "pin", "pin": { "type": "<PIN_OPERATION>", "message_id": "<MESSAGE_ID>", "expiration_days": "<EXPIRATION>" } }
Body parameters
| Placeholder | Description | Sample Value |
|---|---|---|
<GROUP_ID>String | Required The group in which you are pinning a message. | Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD |
<PIN_OPERATION>String | Required The pinning operation you are performing on the group. Can either be "pin" or "unpin" | pin |
<MESSAGE_ID>String | Required A unique identifier for the message you are pinning or unpinning in the group. | wamid.HBgLM... |
<EXPIRATION>Integer | Required when PIN_OPERATION is pinPin duration in days. Can be 1 to 30 days. | 4 |
Response body
{ "messaging_product": "whatsapp", "contacts": [ { "input": "Y2FwaV9ncm91cDo....", "wa_id": "Y2FwaV9ncm91cDo...." } ], "messages": [ { "id": "wamid.HBgLM..." } ] }
Webhooks
Subscribe to the
messages webhook topic to receive message notifications. When you send a pin/unpin message, only a sent message webhook will be triggered. Delivered or read message webhooks will not be triggered.Group message status webhooks
When you send messages to a group, you will receive a webhook when the message is delivered or read.
You receive a single aggregated webhook instead of multiple webhooks.
This means that if you send a message and are set to receive several
read or delivered statuses, you receive a single aggregated webhook containing multiple status objects.Each webhook you receive is only ever in reference to a single message sent to a single group and a single status type.