> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/messaging/groups/messaging-api.md).

# Messaging API

## How to send group messages?

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

## Send Group Message

To send a group message, use the existing send message endpoint:

<mark style="color:$success;">`POST`</mark> `https://waba-v2.360dialog.io/messages`

### What is the difference from the Cloud API?

* The `recipient_type` field now is `group` instead of `individual`.
* The `to` field now supports the `group ID` that is obtained when using the Groups API.

#### **Request example**

```json
curl 'https://waba-v2.360dialog.io/messages' \
-H 'Content-Type: application/json' \
-H 'D360-API-KEY: <API_KEY>' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "group",
  "to": "<GROUP_ID>",
  "type": "text",
  "text": {
      "preview_url": true,
      "body": "This is another destination option: https://www.luckytravel.com/DDLmU5F1Pw"
  }
}'
   
```

#### Webhooks

<details>

<summary>Group Message Sent Example</summary>

```json
{
   "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"
         }
       ]
     }
   ]
 }
```

</details>

<details>

<summary>Group Message Failed Example</summary>

```json
{
   "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": "/docs/whatsapp/cloud-api/support/error-codes/"
                    }
                  ]
                }
              ]
           },
           "field": "messages"
         }
       ]
     }
   ]
 }
```

</details>

{% hint style="warning" %}
For more details on error codes, please consult [Meta's official documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/).
{% endhint %}

## Receive Group Messages

The webhook events will be sent to the same webhook configured for your phone number/WABA.

* The `message` object includes a `group_id` field to indicate this is a group message.&#x20;
* The `from` field in the `message` object and the contact object point to the same participant who sends this message.

#### Webhooks

<details>

<summary>Receive group message webhook sample</summary>

```json
{
  "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"
        }]
  }]
}
```

</details>

<details>

<summary>Receive unsupported group message webhook sample</summary>

```json
{
  "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"
        }
      ]
    }
  ]
}
```

</details>

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

{% hint style="danger" %}
**Limitations:**

* 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.
  {% endhint %}

<mark style="color:$success;">`POST`</mark> `https://waba-v2.360dialog.io/messages`

{% tabs %}
{% tab title="Request body" %}

```json
{
  "messaging_product": "whatsapp",
  "recipient_type": "group",
  "to": "<GROUP_ID>",
  "type": "pin",
  "pin": {
    "type": "<PIN_OPERATION>",
    "message_id": "<MESSAGE_ID>",
    "expiration_days": "<EXPIRATION>"
  }
}
```

{% endtab %}

{% tab title="Body Parameters" %}

| Placeholder                                            | Description                                                                                                                                                         | Sample Value                                              |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| <mark style="color:$success;">`<GROUP_ID>`</mark>      | <p><strong>Required</strong></p><p></p><p>The group in which you are pinning a message.</p>                                                                         | Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD |
| <mark style="color:$success;">`<PIN_OPERATION>`</mark> | <p><strong>Required</strong></p><p></p><p>The pinning operation you are performing on the group.</p><p>Can either be <code>"pin"</code> or <code>"unpin"</code></p> | pin                                                       |
| <mark style="color:$success;">`<MESSAGE_ID>`</mark>    | <p><strong>Required</strong></p><p></p><p>A unique identifier for the message you are pinning or unpinning in the group.</p>                                        | wamid.HBgLM...                                            |
| <mark style="color:$success;">`<EXPIRATION>`</mark>    | <p><strong>Required when <code>PIN\_OPERATION</code> is <code>pin</code></strong></p><p><br></p><p>Pin duration in days. Can be 1 to 30 days.</p>                   | 4                                                         |
| {% endtab %}                                           |                                                                                                                                                                     |                                                           |
| {% endtabs %}                                          |                                                                                                                                                                     |                                                           |

**Expected Outcomes**

{% tabs %}
{% tab title="200: OK" %}

```json
      {
        "messaging_product": "whatsapp",
        "contacts": [
          {
            "input": "Y2FwaV9ncm91cDo....",
            "wa_id": "Y2FwaV9ncm91cDo...."
          }
        ],
        "messages": [
          {
            "id": "wamid.HBgLM..."
          }
        ]
  }
```

{% endtab %}
{% endtabs %}

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

{% hint style="info" %}

## Error codes

Check all the error codes related to the Group API [here](https://developers.facebook.com/docs/whatsapp/cloud-api/groups/error-codes).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/docs/messaging/groups/messaging-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.