WhatsApp Business Platform

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_update
  • group_participants_update
  • group_settings_update
  • group_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_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/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

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