> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookmyapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage groups

> Create, change, and delete groups, handle invite links, remove members, and review join requests.

Every operation works over REST and the CLI, and all but the group photo work over MCP.\

REST calls use your `hmok_` API key and need the scope `channel.manage` to change things, or `channel.read` to read.

| To | REST | CLI | MCP |
| - | - | - | - |
| Create a group | `POST /channels/{ch}/whatsapp/groups` | `groups create` | `create_whatsapp_group` |
| List groups | `GET /channels/{ch}/whatsapp/groups` | `groups list` | `list_whatsapp_groups` |
| Get a group | `GET /channels/{ch}/whatsapp/groups/{groupId}` | `groups get` | `get_whatsapp_group` |
| Change subject or description | `PATCH /channels/{ch}/whatsapp/groups/{groupId}` | `groups update` | `update_whatsapp_group` |
| Set the photo | `PUT /channels/{ch}/whatsapp/groups/{groupId}/photo` | `groups photo` | Not available |
| Delete a group | `DELETE /channels/{ch}/whatsapp/groups/{groupId}` | `groups delete` | `delete_whatsapp_group` |
| Get, reset, or revoke the invite link | `GET`, `DELETE` `/channels/{ch}/whatsapp/groups/{groupId}/invite-link`, `POST` `/channels/{ch}/whatsapp/groups/{groupId}/invite-link/reset` | `groups invite-link` | `whatsapp_group_invite_link` |
| Remove members | `POST /channels/{ch}/whatsapp/groups/{groupId}/participants/remove` | `groups remove` | `remove_whatsapp_group_participants` |
| Review join requests | `GET` `/channels/{ch}/whatsapp/groups/{groupId}/join-requests`, `POST` `/channels/{ch}/whatsapp/groups/{groupId}/join-requests/approve` or `/reject` | `groups join-requests` | `whatsapp_group_join_requests` |

CLI commands start with `hookmyapp whatsapp` and take `--channel` and `--json`.\

Full request and response details are in the [API reference](https://docs.hookmyapp.com/whatsapp/api/groups/create-group.md).

Make sure the number [can use groups](https://docs.hookmyapp.com/whatsapp/groups/overview.md#who-can-use-groups) first.

## Async changes

Creating a group, changing it, setting the photo, removing members, and deleting it finish a moment after the call.\

The call returns `202` with a `requestId`. The result arrives as a [`whatsapp.group.updated` event](https://docs.hookmyapp.com/whatsapp/groups/events) with the same `requestId`.

Send an `Idempotency-Key` header on writes so a retry never runs twice.

## Create a group

```bash REST theme={null}
curl -X POST https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups \
  -H "Authorization: Bearer hmok_..." \
  -H "Content-Type: application/json" \
  -d '{"subject":"Order 1042","description":"Updates for your order","joinApprovalMode":"approval_required"}'
```

```bash CLI theme={null}
hookmyapp whatsapp groups create --channel 15551234567 \
  --subject "Order 1042" \
  --description "Updates for your order" \
  --approval required
```

`joinApprovalMode` is `auto_approve` (anyone with the link joins) or `approval_required` (you approve each person). The CLI takes `--approval auto` or `--approval required`.

The answer is `{ "channelId": "ch_AbCdEf12", "requestId": "..." }`. The group id arrives in the `created` event with the same `requestId`, or find the new group in the list.

## List and read groups

```bash theme={null}
curl "https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups?limit=25" \
  -H "Authorization: Bearer hmok_..."
```

The list returns `groups` (each with `groupId`, `subject`, `createdAt`) and `nextCursor`. Pass `nextCursor` as `cursor` for the next page. `limit` is 1 to 1024.

```bash theme={null}
hookmyapp whatsapp groups list --channel 15551234567
hookmyapp whatsapp groups get GROUP_ID --channel 15551234567
```

A single group also returns `description`, `joinApprovalMode`, `suspended`, `participantCount`, and `participants`. Each participant has `waId` (the phone number) or `userId` (when the member has hidden their phone number).

## Change a group

Send `subject`, `description`, or both.

```bash theme={null}
curl -X PATCH https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups/GROUP_ID \
  -H "Authorization: Bearer hmok_..." \
  -H "Content-Type: application/json" \
  -d '{"subject":"Order 1042, shipped"}'
```

```bash theme={null}
hookmyapp whatsapp groups update GROUP_ID --channel 15551234567 --subject "Order 1042, shipped"
```

## Set the photo

Send one JPEG as `multipart/form-data`, in a part named `file`. It must be square, at least 192 px, and up to 5 MB.

```bash theme={null}
curl -X PUT https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups/GROUP_ID/photo \
  -H "Authorization: Bearer hmok_..." \
  -F "file=@./group.jpg;type=image/jpeg"
```

```bash theme={null}
hookmyapp whatsapp groups photo GROUP_ID --channel 15551234567 --file ./group.jpg
```

Your AI agent can't set the photo over MCP. Use REST or the CLI.

## Delete a group

Deleting a group removes its members.

```bash theme={null}
curl -X DELETE https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups/GROUP_ID \
  -H "Authorization: Bearer hmok_..."
```

```bash theme={null}
hookmyapp whatsapp groups delete GROUP_ID --channel 15551234567
```

The call returns `202` with a `requestId`. The result arrives as a `deleted` event with the same `requestId`. `succeeded` says whether it worked.

## Invite link

| Action | REST | CLI | MCP `action` |
| - | - | - | - |
| Get the link | `GET /channels/{ch}/whatsapp/groups/{groupId}/invite-link` | `groups invite-link GROUP_ID` | `get` |
| Reset it. Earlier links stop working | `POST /channels/{ch}/whatsapp/groups/{groupId}/invite-link/reset` | `groups invite-link GROUP_ID --reset` | `reset` |
| Revoke it | `DELETE /channels/{ch}/whatsapp/groups/{groupId}/invite-link` | `groups invite-link GROUP_ID --revoke` | `revoke` |

The answer holds `inviteLink`. It is `null` after a revoke.

## Remove members

Remove up to 8 members per call. Each is a phone number (`waId`) or a `userId`, as listed on the group.

```bash theme={null}
curl -X POST https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups/GROUP_ID/participants/remove \
  -H "Authorization: Bearer hmok_..." \
  -H "Content-Type: application/json" \
  -d '{"members":["15551234567"]}'
```

```bash theme={null}
hookmyapp whatsapp groups remove GROUP_ID +15551234567 --channel 15551234567
```

Each removal sends a `member_removed` event.

## Join requests

On an `approval_required` group, people who tap the invite link wait for you to approve them.

| Action | REST | CLI | MCP `action` |
| - | - | - | - |
| List pending requests | `GET /channels/{ch}/whatsapp/groups/{groupId}/join-requests` | `groups join-requests GROUP_ID` (`--cursor` for the next page) | `list` |
| Approve | `POST /channels/{ch}/whatsapp/groups/{groupId}/join-requests/approve` | `groups join-requests GROUP_ID --approve REQUEST_ID` | `approve` |
| Reject | `POST /channels/{ch}/whatsapp/groups/{groupId}/join-requests/reject` | `groups join-requests GROUP_ID --reject REQUEST_ID` | `reject` |

```bash theme={null}
curl -X POST https://api.hookmyapp.com/channels/ch_AbCdEf12/whatsapp/groups/GROUP_ID/join-requests/approve \
  -H "Authorization: Bearer hmok_..." \
  -H "Content-Type: application/json" \
  -d '{"joinRequestIds":["JOIN_REQUEST_ID"]}'
```

Approve and reject work on several requests at once. The answer lists `succeeded` ids and `failed` requests with a reason each.

You get a `join_requested` event for every new request.

## Errors

| Code | Meaning |
| - | - |
| `400 WA_GROUPS_NOT_ELIGIBLE` | The number can't use groups. See [who can use groups](https://docs.hookmyapp.com/whatsapp/groups/overview.md#who-can-use-groups) |
| `400 WA_GROUPS_LIMIT` | The number has reached 10,000 groups. Delete groups you no longer use |
| `400 WA_GROUP_CREATE_BLOCKED` | WhatsApp did not allow this group right now. Try again later |
| `429 WA_GROUPS_RATE_LIMITED` | Too many group requests. Wait a minute, then retry (the `Retry-After` header says how long) |
| `404 WA_GROUP_NOT_FOUND` | This group wasn't found on this number |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.