Sending Group Messages

/v1/messages

Use the messages endpoint to send text messages, media messages, or Message Templates to groups of customers.

This document covers:

Prerequisites

Request

Sending a message to a group is very similar to sending a message to an individual. When setting the to parameter, you specify the group ID and set the recipient_type field to group. You can read about these fields in the Sending Text Messages documentation.

Any type of message that can be sent to an individual can also be sent to a group. To create a group and get a group ID, follow the instructions in the Creating Groups documentation.

An additional field that is optional for group messages is render_mentions. This field either makes it true for mentions to be allowed in messages or not. See the Mentions section for more information.

POST /v1/messages   
{
    "preview_url": false | true,
    "recipient_type": "group",
    "to": "whatsapp-group-id",
    "render_mentions": true | false,
    "type": "text",
    "text": {
        "body": "your-text-message-content"
    }
}

Example

POST /v1/messages  
{
    "recipient_type": "group",
    "to": "16315550000-1503342882",
    "render_mentions": false,
    "type": "text",
    "text": {
        "body": "WhatsApp Group Message example"
    }
}

Mentions

You can mention someone in a group to make sure they get a notification. In the body of the message, enter the WhatsApp ID after an at symbol (e.g., @16315550000). You can mention multiple people in the same message.

When the message is delivered, the WhatsApp ID for the user that is mentioned is replaced with either the name from their address book, the user's screen name, or just the phone number if neither of those exists.

Mentions can only be used if the render_mentions parameter is set to true.

Examples

You can use mentions in the body of a text message or in the caption of a media message.

POST /v1/messages    
{
    "recipient_type": "group",
    "to": "16315550000-1503342882",
    "type": "text",
    "render_mentions": true,
    "text": {
        "body": "WhatsApp group message @16315550000 @16315556000."
    }
}

If the person that receives the message has the mentioned phone numbers saved in their address books as Person1 and Person2, the final rendering of the message will be "WhatsApp group message @Person1 @Person2."

Mentions can also be used in media message captions.

POST /v1/messages     
{
    "recipient_type": "group",
    "to": "16315550000-1503342882",
    "type": "image",

    "image": {
        "id": "media-id",
        "caption": "Check out our new shoe collection, @16315550000!"    
    }
}

Response

A successful response will include a message ID. An unsuccessful response will contain an error message. See the Messages — Responses documentation for more information.