WhatsApp Business Platform
WhatsApp Business Platform
Resources

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.

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/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

  1. When calling the API, only one message can be pinned at a time.
  2. Only the group admin can pin or unpin messages.
  3. 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

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
Did you find this page helpful?
Thumbs up icon
Thumbs down icon