Group messaging | Developer Documentation
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:
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_updategroup_participants_updategroup_settings_updategroup_status_updateFor a full reference of webhooks for the Groups API, please visit our Webhooks for Groups API reference.
Send group message
To send a group message, use the existing send message endpoint:
POST /<BUSINESS_PHONE_NUMBER_ID>/messagesThis endpoint has been extended to support group messages in the following way:
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/v25.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
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 status notifications. Standard sent and delivered statuses webhooks will be received for the message_id in the response.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.
No comments to display
No comments to display