# Group operations

Exact methods, permissions, request bodies and query fields for group operations.

## Get all groups for a session

GET /api/v1/channels/{channel_id}/groups

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.





Query parameter | Required | Schema
--- | --- | ---
limit | No | {"type":"integer","minimum":1,"maximum":100}
offset | No | {"type":"integer","minimum":0,"maximum":10000}

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Create a new group

POST /api/v1/channels/{channel_id}/groups

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `name` (string, required): Maximum 100 characters. See JSON schema for all validation constraints.
- `participants` (array, required): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 100
    },
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "required": [
    "name",
    "participants"
  ],
  "additionalProperties": false
}
```





## Preview a group from its invite code, without joining

GET /api/v1/channels/{channel_id}/groups/join-info

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.





Query parameter | Required | Schema
--- | --- | ---
code | Yes | {"type":"string","maxLength":4096}

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get detailed group info

GET /api/v1/channels/{channel_id}/groups/{groupId}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Join a group via invite code

POST /api/v1/channels/{channel_id}/groups/join

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `inviteCode` (string, required): Maximum 128 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "inviteCode": {
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "inviteCode"
  ],
  "additionalProperties": false
}
```





## Get group settings (announce / locked / ephemeral timer / member-add mode)

GET /api/v1/channels/{channel_id}/groups/{groupId}/settings

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Update group settings (announce / locked / ephemeral timer / member-add mode)

PUT /api/v1/channels/{channel_id}/groups/{groupId}/settings

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `announce` (boolean): See JSON schema for all validation constraints.
- `locked` (boolean): See JSON schema for all validation constraints.
- `ephemeralSeconds` (number): See JSON schema for all validation constraints.
- `memberAddMode` (string): Allowed: ["all","admins"]. Maximum 4096 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "announce": {
      "type": "boolean"
    },
    "locked": {
      "type": "boolean"
    },
    "ephemeralSeconds": {
      "type": "number",
      "minimum": 0
    },
    "memberAddMode": {
      "type": "string",
      "enum": [
        "all",
        "admins"
      ],
      "maxLength": 4096
    }
  },
  "additionalProperties": false,
  "required": []
}
```





## Add participants to a group

POST /api/v1/channels/{channel_id}/groups/{groupId}/participants

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `participants` (array, required): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "required": [
    "participants"
  ],
  "additionalProperties": false
}
```





## Remove participants from a group

DELETE /api/v1/channels/{channel_id}/groups/{groupId}/participants

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `participants` (array, required): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "required": [
    "participants"
  ],
  "additionalProperties": false
}
```





## Promote participants to admin

POST /api/v1/channels/{channel_id}/groups/{groupId}/participants/promote

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `participants` (array, required): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "required": [
    "participants"
  ],
  "additionalProperties": false
}
```





## Demote participants from admin

POST /api/v1/channels/{channel_id}/groups/{groupId}/participants/demote

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `participants` (array, required): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "required": [
    "participants"
  ],
  "additionalProperties": false
}
```





## List pending join requests for a group

GET /api/v1/channels/{channel_id}/groups/{groupId}/membership-requests

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Approve pending join requests

POST /api/v1/channels/{channel_id}/groups/{groupId}/membership-requests/approve

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `participants` (array): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "additionalProperties": false,
  "required": []
}
```





## Reject pending join requests

POST /api/v1/channels/{channel_id}/groups/{groupId}/membership-requests/reject

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `participants` (array): Maximum 100 items. Individual WhatsApp IDs; consent is required.



```json
{
  "type": "object",
  "properties": {
    "participants": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "additionalProperties": false,
  "required": []
}
```





## Change group name/subject

PUT /api/v1/channels/{channel_id}/groups/{groupId}/subject

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `subject` (string, required): Maximum 100 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "subject"
  ],
  "additionalProperties": false
}
```





## Change group description

PUT /api/v1/channels/{channel_id}/groups/{groupId}/description

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `description` (string, required): Maximum 1024 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "maxLength": 1024
    }
  },
  "required": [
    "description"
  ],
  "additionalProperties": false
}
```





## Set this account's member label in a group

PUT /api/v1/channels/{channel_id}/groups/{groupId}/member-label

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `label` (string, required): Maximum 30 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "maxLength": 30
    }
  },
  "required": [
    "label"
  ],
  "additionalProperties": false
}
```





## Leave a group

POST /api/v1/channels/{channel_id}/groups/{groupId}/leave

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get the group's picture URL

GET /api/v1/channels/{channel_id}/groups/{groupId}/picture

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Set the group's picture

PUT /api/v1/channels/{channel_id}/groups/{groupId}/picture

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `url` (string): Maximum 2048 characters. See JSON schema for all validation constraints.
- `base64` (string): Maximum 1400000 characters. See JSON schema for all validation constraints.
- `mimetype` (string): Maximum 4096 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048
    },
    "base64": {
      "type": "string",
      "maxLength": 1400000,
      "pattern": "^[A-Za-z0-9+/]+={0,2}$"
    },
    "mimetype": {
      "type": "string",
      "maxLength": 4096
    }
  },
  "additionalProperties": false,
  "required": []
}
```





## Remove the group's picture

DELETE /api/v1/channels/{channel_id}/groups/{groupId}/picture

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get group invite code/link

GET /api/v1/channels/{channel_id}/groups/{groupId}/invite-code

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Revoke group invite code and generate new one

POST /api/v1/channels/{channel_id}/groups/{groupId}/invite-code/revoke

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```