Summary

Use the WhatsApp Groups API to create and manage WhatsApp groups programmatically. You can create groups, send invitations to pending contacts, remove participants, delete groups, and retrieve a list of active groups.

Note: The WhatsApp Groups API is available on the Business plan.

Instructions

Before you start

Before using the WhatsApp Groups API:

Make sure your Wati account is on the Business plan.
Generate a Wati API token and keep it secure.
Use the API base URL provided in your Wati API documentation.

For more information, see Authentication. Wati APIs use Bearer Token authentication, and requests must include the API token in the Authorization header.

Authentication

Include the following headers with your API requests:

Authorization: Bearer <your_api_token>
Content-Type: application/json

For example:

curl --location 'https://live-mt-server.wati.io/xxxxxx/api/ext/v3/conversations/groups' \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'Content-Type: application/json'

Note: Use the API base URL shown in your Wati account (Connectors > API Docs > API Endpoint) rather than the example URL above.

Security: Never share your API token or commit it to public code. Wati recommends storing API credentials in environment variables or a secrets manager.

Available endpoints

Method	Endpoint	Description
`POST`	`/api/ext/v3/conversations/groups`	Create a WhatsApp group
`DELETE`	`/api/ext/v3/conversations/groups/{groupId}`	Delete a WhatsApp group
`POST`	`/api/ext/v3/conversations/groups/{groupId}/invites`	Send invitations to pending contacts
`DELETE`	`/api/ext/v3/conversations/groups/{groupId}/participants`	Remove participants from a group
`POST`	`/api/ext/v3/conversations/groups/list`	List active WhatsApp groups

1. Create a WhatsApp group

POST /api/ext/v3/conversations/groups

Creates a new WhatsApp group.

You can optionally specify a channel. If you don't specify a channel, the default channel is used. Operators are identified by email address, while contacts are identified by phone number or supported contact target.

Request body

{
  "channel": "MyChannel",
  "name": "VIP Support Group",
  "description": "Group for VIP customers",
  "owner_email": "[email protected]",
  "operator_emails": [
    "[email protected]"
  ],
  "contact_targets": [
    "14155551234",
    "14155555678"
  ],
  "join_approval_mode": "auto_approve"
}

Request body parameters

Field	Type	Description
`channel`	string	The channel to use. If omitted, the default channel is used.
`name`	string	The name of the WhatsApp group.
`description`	string	The description of the WhatsApp group.
`owner_email`	string	Email address of the group owner.
`operator_emails`	array	Email addresses of operators to add to the group.
`contact_targets`	array	Phone number, BSUID, or ContactId of the contacts to add to the group. Maximum 7 contacts per group.
`join_approval_mode`	string	Specifies the group join approval mode.

Response

A successful request returns 201 Created and the details of the newly created group.

{
  "group": {
    "id": "6828abc123def456789012ab",
    "name": "VIP Support Group",
    "description": "Group for VIP customers",
    "invite_link": "",
    "channel_id": "ch_123",
    "conversation_id": "conv_456",
    "operators": [
      {
        "id": "682800000000000000000001",
        "operator_id": "op_id",
        "name": "Owner Name",
        "role": "owner",
        "added_at": "2026-08-13T08:27:00.8447035Z"
      }
    ],
    "contacts": [
      {
        "id": "682800000000000000000003",
        "contact_id": "contact_id",
        "wa_id": "+14155551234",
        "name": "Contact Name",
        "join_status": "pending"
      }
    ],
    "created_at": "2026-08-13T08:27:00.8448051Z"
  }
}

Response codes

Code	Description
`201`	The group was created successfully.
`400`	The request is invalid.
`401`	The request is unauthorized.
`403`	The request is forbidden.
`429`	Too many requests.
`500`	An unexpected error occurred.

2. Delete a WhatsApp group

DELETE /api/ext/v3/conversations/groups/{groupId}

Deletes the specified WhatsApp group.

If the group has already been deleted, the endpoint still returns 200 OK.

Path parameters

Parameter	Type	Required	Description
`groupId`	string	Yes	The ID of the group to delete.

Response

A successful request returns 200 OK.

{
  "result": true
}

Response codes

Code	Description
`200`	The group was deleted successfully.
`400`	The request is invalid.
`401`	The request is unauthorized.
`403`	The request is forbidden.
`429`	Too many requests.
`500`	An unexpected error occurred.

3. Send group invitations

POST /api/ext/v3/conversations/groups/{groupId}/invites

Sends a group invitation to all contacts that are still pending.

The API checks the contacts in the group, identifies those with a pending join status, and sends the group invite template to each contact's 1:1 conversation.

Path parameters

Parameter	Type	Required	Description
`groupId`	string	Yes	The ID of the group to send invitations for.

Response

A successful request returns the invitation result for each pending contact.

{
  "total_pending": 3,
  "sent": 2,
  "failed": 1,
  "results": [
    {
      "contact_name": "Alice",
      "phone": "14155551234",
      "success": true
    },
    {
      "contact_name": "Bob",
      "phone": "14155555678",
      "success": true
    },
    {
      "contact_name": "Charlie",
      "phone": "",
      "success": false,
      "error": "BSUID-only contact, no phone number"
    }
  ]
}The response includes:

total_pending: Number of contacts with a pending join status.
sent: Number of invitations sent successfully.
failed: Number of invitations that could not be sent.
results: Invitation result for each pending contact.

Response codes

Code	Description
`200`	The invitation results were returned successfully.
`400`	The request is invalid.
`401`	The request is unauthorized.
`403`	The request is forbidden.
`429`	Too many requests.
`500`	An unexpected error occurred.

4. Remove participants from a WhatsApp group

DELETE /api/ext/v3/conversations/groups/{groupId}/participants

Removes operators and/or contacts from a WhatsApp group.

You must provide at least one operator email or contact target.

Path parameters

Parameter	Type	Required	Description
`groupId`	string	Yes	The ID of the group to remove participants from.

Request body

{
  "operator_emails": [
    "[email protected]"
  ],
  "contact_targets": [
    "14155551234"
  ]
}

Request body parameters

Field	Type	Description
`operator_emails`	array	Email addresses of operators to remove from the group.
`contact_targets`	array	Phone number, BSUID, or ContactId of the contacts to add to the group. Maximum 7 contacts per group.

You can provide operator_emails, contact_targets, or both. At least one must be provided.

Response

A successful request returns 200 OK.

{
  "result": true
}

Response codes

Code	Description
`200`	The participants were removed successfully.
`400`	The request is invalid.
`401`	The request is unauthorized.
`403`	The request is forbidden.
`429`	Too many requests.
`500`	An unexpected error occurred.

5. List active WhatsApp groups

POST /api/ext/v3/conversations/groups/list

Returns a cursor-paginated list of active WhatsApp groups.

You can optionally filter the results by channel or specific group IDs. If you don't specify a channel, the default channel is used.

Request body

{
  "channel": "MyChannel",
  "limit": 20
}

Request body parameters

Field	Type	Description
`channel`	string	The channel to use. If omitted, the default channel is used.
`limit`	integer	The number of groups to return in the response.

Response

A successful request returns 200 OK with the active groups and pagination information.

{
  "groups": [
    {
      "id": "6828abc123def456789012ab",
      "name": "VIP Support Group",
      "description": "Group for VIP customers",
      "invite_link": "https://chat.whatsapp.com/abc123",
      "channel_id": "ch_123",
      "conversation_id": "conv_456",
      "operators": [
        {
          "id": "682800000000000000000001",
          "operator_id": "op_id",
          "name": "Owner",
          "role": "owner",
          "added_at": "2026-08-13T08:27:00.8595387Z"
        }
      ],
      "contacts": [
        {
          "id": "682800000000000000000003",
          "contact_id": "contact_id",
          "wa_id": "+14155551234",
          "name": "Alice",
          "join_status": "joined",
          "joined_at": "2026-08-13T08:27:00.8595402Z"
        }
      ],
      "created_at": "2026-08-13T08:27:00.8595404Z"
    }
  ],
  "continuous_token": "eyJsIjoiNjgyOGFiYzEyM2RlZjQ1Njc4OTAxMmFiIn0=",
  "total": 5
}

Pagination

The List Groups endpoint returns results in pages.

If more groups are available, the response includes a continuous_token. Use this token to retrieve subsequent pages.

When continuous_token is absent or null, there are no more results.

Response codes

Code	Description
`200`	The list of active groups was returned successfully.
`400`	The request is invalid.
`401`	The request is unauthorized.
`403`	The request is forbidden.
`429`	Too many requests.
`500`	An unexpected error occurred.

Error responses

The following HTTP status codes can be returned by the WhatsApp Groups API endpoints:

Code	Description
`400`	The request is invalid.
`401`	The request is unauthorized.
`403`	The request is forbidden.
`429`	Too many requests.
`500`	An unexpected error occurred.

For 400, 403, and 500 responses, the API can return additional details such as an error code, message, and timestamp.

Example error response

{
  "details": "string",
  "code": 0,
  "message": "string",
  "timestamp": "2026-08-13T09:01:03.204Z"
}

For authentication-related errors, verify that your request includes a valid API token in the Authorization header. See Authentication for more information.

WhatsApp Groups API: Create, Manage, and Delete Groups

Summary

Instructions

Before you start

Authentication

Available endpoints

1. Create a WhatsApp group

Request body

Request body parameters

Response

Response codes

2. Delete a WhatsApp group

Path parameters

Response

Response codes

3. Send group invitations

Path parameters

Response

Response codes

4. Remove participants from a WhatsApp group

Path parameters

Request body

Request body parameters

Response

Response codes

5. List active WhatsApp groups

Request body

Request body parameters

Response

Pagination

Response codes

Error responses

Example error response