> ## Documentation Index
> Fetch the complete documentation index at: https://whatsapp-docs.kap.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Groups messaging
# Group messaging
Updated: Nov 14, 2025
## Overview
This document provides comprehensive information on the APIs and webhooks available 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
In order to receive webhook notifications for metadata about your groups, please subscribe to the following webhook fields:
`group_lifecycle_update`
`group_participants_update`
`group_settings_update`
`group_status_update`
For a full reference of webhooks for the Groups API, please visit our [Webhooks for Groups API reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/webhooks).
## Send group message
To send a group message, use the existing send message endpoint:
`POST /<BUSINESS_PHONE_NUMBER_ID>/messages`
This endpoint has been extended to support group messages in the following way:
The `recipient_type` field now supports `group` as well as `individual`.
The `to` field now supports the `group ID` that is obtained when using the Groups API.
### Example group message send
```
curl 'https://graph.facebook.com/v24.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.
### 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>"\
},\
"wa_id": "<WHATSAPP_USER_PHONE_NUMBER>"\
}],\
"messages": [{\
"from": "<GROUP_PARTICIPANT_PHONE_NUMBER>",\
"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>"\
},\
"wa_id": "<WHATSAPP_USER_PHONE_NUMBER>"\
}\
],\
"messages": [\
{\
"from": "<GROUP_PARTICIPANT_PHONE_NUMBER>",\
"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>/messages`
**Note: 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 `pin`**
Pin 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 status notifications. Standard sent and delivered statuses webhooks will be received for the `message_id` in the response.
[Learn more about the messages `status` webhook object here](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
## Group message status webhooks
When you send messages to a group, you will receive a webhook when the message is delivered or read.
Instead of sending multiple webhooks for each status update, we will send an aggregated webhook.
This means that if you send a message and are set to receive several `read` or `delivered` statuses, we will send you a single, aggregated webhook that contains 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.
[Learn more about the Group Message Status webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/webhooks#group-message-status-webhooks)
Did you find this page helpful?
ON THIS PAGE
Overview
Subscribe to groups metadata webhooks
Send group message
Example group message send
Webhooks
Group message sent example
Group message failed example
Receive group messages
Webhooks
Receive group message webhook sample
Receive unsupported group message webhook sample
Pin and unpin group message
Limits
Request Syntax
Request body
Body parameters
Response body
Webhooks
Group message status webhooks
***