Group Management

This page will help you to manage the groups.

Overview

The Groups API gives you simple functions to control groups through their lifecycle.

When you create a new group, an invite link is created for inviting participants to the group.

Since you cannot manually add participants to the group, simply send a message with your invite link to WhatsApp users whom you would like to join the group.

Create a Group Invite Link Template Message

To create a template message that includes a group invite link, you can choose from two primary methods:

Using the WhatsApp Manager: This is a graphical, user-friendly interface suitable for manual creation.
Using the API: This method allows for automated or programmatic creation and is suitable for integration with other systems.

Via WhatsApp Manager

Access your WhatsApp Business Account

Under Message templates > Template Library

Click on Group Invite Link and select the desired template

Name your template and submit for review

Once approved, you will be able to start using this template message for inviting users to your group.

Via API

Create a new template using the template creation endpoint

POST https://waba-v2.360dialog.io/v1/configs/templates

Payload:

Use the group_invite_link in the library_template_name parameter.

{
  "name": "test_template",
  "category": "UTILITY",
  "language": "en_US",
  "library_template_name": "group_invite_link"
  "components": [
  ...
  <MORE_CONTENT_HERE>
  }]
}

Once approved, start using it.

Please check our Template section to add more parameters to your template message.

Create a group

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

curl --location 'https://waba-v2.360dialog.io/groups' \
--header 'D360-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "messaging_product": "whatsapp",
  "subject": "<GROUP_SUBJECT>",
  "description": "<GROUP_DESCRIPTION>",
  "join_approval_mode": "<JOIN_APPROVAL_MODE>"
}'

{
  "messaging_product": "whatsapp",
  "subject": "<GROUP_SUBJECT>",
  "description": "<GROUP_DESCRIPTION>",
  "join_approval_mode": "<JOIN_APPROVAL_MODE>"
}

Once the group is created, you will receive a webhook with a invite_link parameter that contains an invite link for the group. You can send this invite link to WhatsApp users interested in joining the group.

Optionally, you can create a group that requires join approval. This means that if a WhatsApp user wants to join your group, you can approve or reject their request.

A group_lifecycle_update webhook is triggered, and you will receive another webhook showing the outcome: succeed or fail.

Groups with join requests

You can create groups that require join request approval. Once enabled, WhatsApp users who click the group invitation link can submit a request to join the group, or cancel a prior request. To do this, set the join_approval_mode to approval_required when creating the group.

When a WhatsApp user joins the group using a join request, a group_participants_update webhook for a user accepting the join request is triggered.

Get join requests

You can also get a list of open join requests via API.

GET https://waba-v2.360dialog.io/groups/{group_id}/join_requests

Request parameters

Placeholder

Description

Sample Value

<GROUP_ID>

Required. Group ID.

Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD

Expected Outcomes

{
  "data": [
    {
      "join_request_id": "<JOIN_REQUEST_ID>",
      "wa_id": "<WHATSAPP_USER_ID>",
      "creation_timestamp": "<JOIN_REQUEST_CREATION_TIMESTAMP">
    },
    //Additional join request objects would follow, if any
  ],
  "paging": {
    "cursors": {
      "before": "<BEFORE_CURSOR>",
      "after": "<AFTER_CURSOR>"
    }
  }
}

Response Parameters

Placeholder

Description

Sample Value

<JOIN_REQUEST_ID>

Join request ID

MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw

<WHATSAPP_USER_ID>

WhatsApp user ID

16505551234

<JOIN_REQUEST_CREATION_TIMESTAMP>

Unix timestamp indicating when the join request was created

1755548877

<BEFORE_CURSOR>

Before cursor

eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3NTU1NTM3MDUxNzUwNTQ1MTAifQZDZD

<AFTER_CURSOR>

After cursor

eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3NTU1NTM3MDUxNzUwNTQ1MTAifQZDZD

Approve join requests

POST https://waba-v2.360dialog.io/groups/{group_id}/join_requests

Request example

curl --location --globoff 'https://waba-v2.360dialog.io/groups/{group_id}/join_requests' \
--header 'D360-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "messaging_product": "whatsapp",
  "join_requests": [
    "<JOIN_REQUEST_ID>"
  ]
}'

Placeholder

Description

Sample Value

<GROUP_ID>

Required. Group ID.

Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD

Expected Outcomes

Upon success, the API will respond with the following JSON payload, and WhatsApp users whose join requests were approved will be able to access the group when tapping the invite link.

{
  "messaging_product": "whatsapp",
  "approved_join_requests": [
    "<JOIN_REQUEST_ID>",
    // Additional join request IDs would go here, it approved in bulk 
  ],

  //Only included if unable to approve one or more join requests 
    
  "failed_join_requests": [
    {
      "join_request_id": "<JOIN_REQUEST_ID>",
      "errors": [
        {
          "code": "<ERROR_CODE>",
          "message": "<ERROR_MESSAGE>",
          "title": "<ERROR_TITLE>",
          "error_data": {
            "details": "<ERROR_DETAILS>"
          }
        }
      ]
    }
  ],
  "errors": [
    {
      "code": "<ERROR_CODE>",
      "message": "<ERROR_MESSAGE>",
      "title": "<ERROR_TITLE>",
      "error_data": {
        "details": "<ERROR_DETAILS>"
      }
    }
  ]
}

Response Parameters

Placeholder

Description

Sample Value

<JOIN_REQUEST_ID>

ID of approved join request, or ID of failed join request, if we were unable to approve

MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw

<ERROR_CODE>

Error code, if unable to approve

131203

<ERROR_MESSAGE>

Error message, if unable to approve

(#131203) Recipient has not accepted our new Terms of Service and Privacy Policy.

<ERROR_TITLE>

Error title, if unable to approve

Unable to add participant to group

<ERROR_DETAILS>

Error details, if unable to approve

Recipient has not accepted our new Terms of Service and Privacy Policy.

Webhooks

A group_participants_update webhook is triggered.

View the "User accepts join request" sample webhook

Reject join requests

DELETE https://waba-v2.360dialog.io/groups/{group_id}/join_requests

Request example

curl --location --globoff --request DELETE 'https://waba-v2.360dialog.io/groups/{group_id}/join_requests' \
--header 'D360-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "messaging_product": "whatsapp",
  "join_requests": [
    "<JOIN_REQUEST_ID>",
    //Additional join request IDs would go here, it rejecting in bulk
  ]
}'

Placeholder

Description

Sample Value

<GROUP_ID>

Required. Group ID.

Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD

<JOIN_REQUEST_ID>

Required. ID of join request to reject.

MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw

Expected Outcomes

Upon success, the API will respond with the following JSON payload, and the WhatsApp user will see the Request to join button again when accessing the group invite link

{
  "messaging_product": "whatsapp",
  "rejected_join_requests": [
    "<JOIN_REQUEST_ID>",
    //Additional join request IDs would go here, it rejecting in bulk 
  ],

  //Only included if unable to reject one or more join requests
  "failed_join_requests": [
    {
      "join_request_id": "<JOIN_REQUEST_ID>",
      "errors": [
        {
          "code": "<ERROR_CODE>",
          "message": "<ERROR_MESSAGE>",
          "title": "<ERROR_TITLE>",
          "error_data": {
            "details": "<ERROR_DETAILS>"
          }
        }
      ]
    }
  ],
  "errors": [
    {
      "code": "<ERROR_CODE>",
      "message": "<ERROR_MESSAGE>",
      "title": "<ERROR_TITLE>",
      "error_data": {
        "details": "<ERROR_DETAILS>"
      }
    }
  ]
}

No webhooks are triggered for rejection.

Get and Reset Group Invite Link

An invite link for the group is generated when the group is created. Use these endpoints to get and reset group invite links.

Once an invite link is reset, all previous invite links will become invalid.

For each endpoint, you will need your group ID to get or reset a link for the correct group as follows:

(maybe put here how to get the group id)

Placeholder

Description

Sample Value

<GROUP_ID>

Required. The ID of the group you want to get or reset an invite link for.

Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD

Get Group Invite Link

GET https://waba-v2.360dialog.io/groups/{group_id}/invite_link

Expected Outcomes

{
  "messaging_product": "whatsapp",
  "invite_link": "https://chat.whatsapp.com/<LINK_ID>"
}

Note that invite_link always begins with the prefix https://chat.whatsapp.com/. The only variable portion is <LINK_ID>

Reset Group Invite Link

POST https://waba-v2.360dialog.io/groups/{group_id}/invite_link

{
  "messaging_product": "whatsapp",
}

Expected Outcomes

{
  "messaging_product": "whatsapp",
  "invite_link": "https://chat.whatsapp.com/<LINK_ID>"
}

Delete Group

This endpoint deletes the group and removes all participants, including the business. No request body is required.

DELETE https://waba-v2.360dialog.io/groups/{group_id}

Placeholder

Description

Sample Value

<GROUP_ID>

Required.

The ID of the group you want to delete.

Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD

Webhooks

A group_lifecycle_update webhook is triggered.

For more details about webhooks, please check the following links:

Delete group succeed
View the "Delete group succeed" sample webhook
Delete group fails
View the "Delete group fails" sample webhook

Remove Group Participants

Check the steps below to remove participants from the group.

Note: If a participant is removed from a group, they can no longer join the group via an invite link.

DELETE https://waba-v2.360dialog.io/groups/{group_id}/participants

Placeholder

Description

Sample Value

"participants": []

Optional

Specifies an array of phone numbers or WhatsApp IDs of WhatsApp accounts. The business phone number used to create the group is always added to the group as the creator and admin.

Max 8 participants
The array cannot be empty.

{ "user": "+17865347866" }, 
{ "user": "+7669992245" },
...

{
  "messaging_product": "whatsapp",
  "participants": [
    { "user": "<WHATSAPP_USER_PHONE_NUMBER> or <WHATSAPP_USER_ID>" },
    { "user": "<WHATSAPP_USER_PHONE_NUMBER> or <WHATSAPP_USER_ID>"" },
    ...
  ]
}

Webhooks

A group_participants_update webhook is triggered.

Get Group Info

Use this to retrieve metadata about a single group.

Note: Specifying no fields in the query parameters will just return the group ID and messaging product.

GET https://waba-v2.360dialog.io/groups/{group_id}

Request example

curl --location --globoff --request GET 'https://waba-v2.360dialog.io/groups/{group_id}?fields=description%2Cparticipants' \
--header 'D360-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "messaging_product": "whatsapp",
  "join_requests": [
    "<JOIN_REQUEST_ID>"
  ]
}'

Placeholder

Description

Sample Value

<GROUP_ID>

Required

The ID of the group you are querying info from.

Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD

<FIELDS>

Optional

A comma-separated list of fields to return. If no fields are passed in, only the group id is returned.

"subject,description,participants,join_approval_mode"

Available Fields

Field

Description

Sample Return Value

join_approval_mode

Indicates if WhatsApp users who click the inviation link can join the group with or without being approved first.

Values can be:

approval_required — Indicates WhatsApp users must be approved via join request before they can access the group.
auto_approve — Indicates WhatsApp users can join the group without approval.

auto_approve

subject

The subject for the group.

"Artificial Intelligence Insights"

description

The group description, if set during creation time.

"Explore AI developments, share knowledge, and discuss the future of artificial intelligence with fellow enthusiasts and experts."

suspended

Returns true if the group has been suspended by whatsapp.

false

creation_timestamp

UNIX timestamp in seconds at which the group was created.

683731200

participants

A list of objects {"wa_id": "<WA_ID>"}, where <WA_ID> is a participant in the group being queried.

[{"wa_id": "2228675309"}, {"wa_id": "7693349922"}]

total_participant_count

The total number of participants in the group, excluding your business.

Expected Outcomes

{
  "messaging_product": "whatsapp",
  "id": "<GROUP_ID>",
  "subject": "<SUBJECT>",
  "creation_timestamp": "<TIMESTAMP>",
  "suspended": "<SUSPENDED>",
  "description": "<DESCRIPTION>",
  "total_participant_count": "<TOTAL_PARTICIPANT_COUNT>",
  "participants": [
    {
      "wa_id": "<WA_ID>"
    },
    {
      "wa_id": "<WA_ID>"
    }
  ],
  "join_approval_mode": "<JOIN_APPROVAL_MODE>"
}

Get Active Groups

Use this to retrieve a list of active groups for a given business phone number.

GET https://waba-v2.360dialog.io/groups

Request example

curl --location 'https://waba-v2.360dialog.io/groups' \
--header 'D360-API-KEY: <API_KEY>'

 ?limit=<LIMIT>, // Optional
  &after=<AFTER_CURSOR>, // Optional
  &before=<BEFORE_CURSOR> // Optional

Expected Outcomes

{ 
  "data": {
    "groups": [
      {"id": "GROUP_ID", "subject": SUBJECT, "created_at": "TIMESTAMP"},
      {"id": "GROUP_ID", "subject": SUBJECT, "created_at": "TIMESTAMP"}
      …
    ]
  },
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/VERSION/PHONE_NUMBER_ID/groups?limit=10&before=NDMyNzQyODI3OTQw",
    "next": "https://graph.facebook.com/VERSION/PHONE_NUMBER_ID/groups?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Response Parameters

Parameter

Description

data[groups]

A list of groups, each containing the group id, group subject, and UNIX timestamp for group creation.

paging

A pagination object.

Update Group Settings

Use this request to update your group's subject, description, and photo.

POST https://waba-v2.360dialog.io/groups/{group_id}

{
  "messaging_product": "whatsapp",
  "subject": "<GROUP_SUBJECT>",
  "profile_picture_file": "<FILE_PATH>",
  "description": "<GROUP_DESCRIPTION>",
}

Placeholder

Description

Sample value

<FILE_PATH>

Optional

A path to an image file stored in your local directory.

To upload a file: Follow the same request structure as the Upload Media endpoint.

Sample file upload cURL:

curl 'https://graph.facebook.com/v23.0/<GROUP_ID> \
-X POST \
-H 'Authorization: Bearer ...' \
-F 'messaging_product=whatsapp' \
-F 'file=@/media/pictures/square_pic.png'

Group profile picture requirement:

Only support mime type image/jpeg
Maximum size: 5MB
Image should be in square, that is, height = width.
Minimum size: 192 x 192

/local/path/file.jpg

<GROUP_SUBJECT>

Optional

The new subject for the group.

Max length: 128 characters
Must not be empty if provided.

"Watch Enthusiasts"

<GROUP_DESCRIPTION>

Optional

The new description for the group.

Max length: 2048 characters

"Join our community to discuss the latest timepieces, share watch reviews, and connect with fellow horology enthusiasts."

Webhooks

A group_settings_update webhook is triggered.

PreviousGroup Messaging NextMessaging API

Last updated 5 minutes ago

Was this helpful?