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:

POST 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

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

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

For more details on error codes, please consult Meta's official documentation.

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.

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

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.

POST https://waba-v2.360dialog.io/messages

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

Expected Outcomes

200: OK

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

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.

Error codes

Check all the error codes related to the Group API here.