Groups (Beta)

/v1/groups

Use the groups node to create and manage groups. When you send a request to create a group, the response contains a group ID field that you can use to send messages to the group and accomplish other tasks.

This document covers:

For information on sending messages to groups, see the Group Messages documentation.

A business cannot be added to a group or join a group. A business can only create groups and manage those same groups.

Creating Groups

Create a group by providing a subject or title for the group. In response, you will receive a group ID that you will use to send messages to the group, manage the group, etc.

POST /v1/groups

{    
  "subject": "your-group-subject"
}

Parameters

NameRequiredDescription

subject

Yes

The subject or title of the group

Request

curl -X POST \
  https://your-webapp-hostname:your-webapp-port/v1/groups \
  -H 'Authorization: Bearer your-auth-token' \
  -H 'Content-Type: application/json' \
  -d '{
      "subject": "your-group-subject"
   }'

Response

The response to the request to create a group returns a group ID that you will use for sending messages to the group, managing the group, etc. If you need to get the group ID at another time, see the Viewing Groups section.

{
    "groups": [{
       "creation_time": timestamp,
       "id": "your-group-id"
    }]
}

The following fields are returned in a successful response:

NameDescription

creation_time

Creation time at client

id

Group identifier for the newly created group
Must be used to uniquely identify groups in subsequent requests, where group_id is used.

Retrieving All Groups

Retrieve all groups where the WhatsApp Business API Client is a participant.

Request

GET /v1/groups

Response

The response returns the group IDs for all groups where the WhatsApp Business API Client is a participant. You can get more information about the group, such as the list of participants and the subject of the group, using the call described in the Retrieving Group Information section.

{
    "groups": [
       {"id": "group-id1"},
       {"id": "group-id2"}
    ]
}

The following fields are returned in a successful response. If no groups exist, an empty groups JSON array is returned.

NameDescription

id

List of groups that WhatsApp Business API Client participates in

Retrieving Group Information

Use this call to get information about the group, including the WhatsApp ID of the participants, and the subject of the group. This call will not return the group icon. To get the group icon, see the Managing the Group Icon section.

Request

GET /v1/groups/your-group-id

Response

{
    "groups": [{
       "admins": [ "whatsapp-id-1", "whatsapp-id-2" ],
       "creation_time": timestamp,
       "creator": "whatsapp-id-1",
       "participants": [ "whatsapp-id-3", "whatsapp-id-4", "whatsapp-id-5" ],
       "subject": "your-group-subject"
    }]
}

The following fields are returned in a successful response:

NameTypeDescription

admins

Array

Group administrators
Lists IDs of the creator of the group and any administrators added as described in the Managing Group Admins section.

creation_time

Int

Group creation time

creator

String

ID of the creator of this group

participants

Array

Participants of the group
This is an array of all the IDs of the participants in the group. Initially, this will be the creator of the group. Invite users to group the group by creating a group invite link, as described in the Group Invite Links.

subject

String

Subject of the group

Updating Group Information

Request

PUT /v1/groups/your-group-id

{
  "subject": "new-group-subject"
}

Parameters

NameRequiredDescription

subject

Yes

Update the group subject to this value

Response

A successful response will show 200 OK and either null or {}. If the group ID is not found, the response will show 404 Not Found and contain no body.

If you receive a different error message, see Error and Status Messages for more information.

Group Invite Links

Request

GET /v1/groups/your-group-id/invite

Response

{
    "groups": [{
    "link": "group-invite-link"
    }]
}

The following fields are returned in a successful response:

NameDescription

link

The link to the group invite

When you have the link to invite participants to join the group, send the link in a text message. When the user clicks on the message, they are invited to join the group.

Request

DELETE /v1/groups/your-group-id/invite

Response

A successful response will show 200 OK and either null or {}. If the group isn't found, a 404 response code is returned with an appropriate error object.

If you receive a different error message, see Error and Status Messages for more information.

Adding or Deleting Group Participants

Add Group Participants

You cannot add participants directly to the group. Participants can only be invited to join the group. Create a link to the invitation as described in the Create a link participants can use to join the group section.

Delete Group Participants

Request

DELETE /v1/groups/your-group-id/participants

{
    "wa_ids": [
        "whatsapp-id-1",
        "whatsapp-id-2"
    ]
}

Parameters

NameRequiredDescription

wa_ids

Yes

The WhatsApp IDs of the participants to remove from the group

Response

A successful response will show 200 OK and either null or {}. If the WhatsApp ID is not found, the response will show 404 Not Found and contain no body.

If you receive a different error message, see Error and Status Messages for more information.

Leaving a Group

Leaving a group means that you are removing yourself from the group participants list.

Request

POST /v1/groups/your-group-id/leave

Response

A successful response will show 200 OK and either null or {}. If the user making the request is not in that group or if the group ID is not found, the response will show 404 Not Found and contain no body.

If you receive a different error message, see Error and Status Messages for more information.

Unused Groups

If you have several unused groups associated with your WhatsApp Account, you may encounter the "Too many groups created" error. Or you may want to simply clean up groups you are no longer using.

  1. Retrieve a list of all your groups.
  2. Leave the groups you are no longer using.

Managing the Group Icon

Set the Group Icon

To set an icon of a group, you must upload the image and associate it with a group ID. You must contain the binary image data and the Content-Type header must be set to the type of the media being uploaded, just like uploading media using the media node.

POST /v1/groups/your-group-id/icon
Content-Type: image/jpeg or other appropriate type
Content-Length: content-size

binary-image-content

Sending binary data in a POST HTTP request is a standard way of uploading binary data. If you want to upload an image, for example, you issue a POST request with the actual image bytes in the payload. Alternatively, you can use cURL with the --data-binary option to read and use the given file in binary exactly as given.

Request

curl -X POST \
  https://your-webapp-hostname:your-webapp-port/v1/your-group-id/icon \
  -H 'Authorization: Bearer your-auth-token' \ 
  -H 'Content-Type: image/jpeg' \
  --data-binary @your-file-path

Response

A successful response will show 200 OK and either null or {}.

If you receive an error message, see Error and Status Messages for more information.

Get the Group Icon

You can get the group icon as either base64-encoded binary content or as a public URL of the image.

Get the Photo Binary

You can get the group icon via direct download.

Request
GET /v1/groups/your-group-id/icon
Response

The response contains the binary image content and the appropriate Content-Type.

Content-Type: image/jpeg or other appropriate type
Content-Length: content-size

binary-image-content

A successful response returns HTTP 200 OK and the binary image content. If an icon is not set for the group, the response is HTTP 404 Not Found with no message body. If the group ID is not valid, the response can be HTTP 400 Bad Request.

Get the Photo URL

You can ask the Coreapp to provide a URL link to download the binary content.

Request
GET /v1/groups/your-group-id/icon?format=link
Response
{
    "groups": [{
        "icon": {
            "link": "public-url-of-group-icon"
        }
    }]
}

If an icon is not set for the group, the response is HTTP 404 Not Found with no message body. If the group ID is not valid, the response can be HTTP 400 Bad Request.

Delete the Group Icon

Request

DELETE /v1/groups/you-group-id/icon

Response

A successful response will show 200 OK and either null or {}. If the media is not found, the response will show 404 Not Found and an appropriate error object.

If you receive a different error message, see Error and Status Messages for more information.

Managing Group Admins

Add Group Admins

The person who created the group is a group administrator, by default. If you want to add other administrators for the group, use the admins endpoint. To see who is listed as an administrator for a group, follow the steps in the Retrieving Group Information section.

Request

PATCH /v1/groups/your-group-id/admins
{
    "wa_ids": [
        "whatsapp_id_1",
        "whatsapp_id_2"
    ]
}

Parameters

NameRequiredDescription

wa_ids

Yes

The WhatsApp IDs of the people to be added as group admins

Response

A successful response will show 200 OK and either null or {}.

If you receive an error object, see Error and Status Messages for more information.

Remove Group Admins

To remove someone as the administrator of a group, use the admins endpoint. To see who is listed as an administrator for a group, follow the steps in the Retrieving Group Information section.

Request

DELETE /v1/groups/your-group-id/admins
{
    "wa_ids": [
        "whatsapp-id-1"
    ]
}

Parameters

NameRequiredDescription

wa_ids

Yes

The WhatsApp IDs of the people to be removed as group admins

Response

A successful response will show 200 OK and either null or {}.

If you receive an error object, see Error and Status Messages for more information.