# WhatsApp groups

> Create and manage groups with the Groups API, send and receive group messages, and the group.* events.

Meta's [Groups API](https://developers.facebook.com/docs/whatsapp/cloud-api/groups) lets an **API-only** number create and manage small groups. In Messajo it exists **through the API only**: the panel has no groups screen.

## Before you start

- An **API-only** WhatsApp connection. In coexistence, `422` [`group_not_supported`](/en/errors#group_not_supported).
- In your Meta app's webhook, the `group_lifecycle_update`, `group_participants_update`, `group_settings_update` and `group_status_update` fields subscribed.
- A key with `send` to create, edit and moderate, `read` to read and `admin` to delete.

## Create

```bash
curl https://api.messajo.com/v1/groups \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_...",
    "subject": "Saturday class",
    "description": "Class announcements",
    "join_approval_mode": "approval_required"
  }'
```

The group starts as `creating` (`grp_…`). Meta creates it in the background and reports by webhook: success → `active` with the `invite_link` and the `group.created` event; failure → `failed` and `group.create_failed` with the reason. `subject` is up to 128 characters and `description` up to 2048.

| Status | Meaning |
|---|---|
| `creating` | waiting for Meta |
| `active` | ready for messages |
| `suspended` | suspended by Meta |
| `deleting` · `deleted` | deleted |
| `failed` | Meta did not create it |

## Manage

| Call | What it does |
|---|---|
| `GET /v1/groups` · `GET /v1/groups/{id}` | lists and reads (subject, description, participants, status) |
| `PATCH /v1/groups/{id}` | changes subject and description; as `multipart/form-data`, the `picture` field changes the photo (square JPEG, ≥ 192 px, up to 5 MiB) |
| `GET /v1/groups/{id}/invite-link` · `POST …/invite-link/reset` | reads or generates a new invite link (the old one stops working) |
| `POST /v1/groups/{id}/participants/remove` | `{ "participants": [{ "wa_id": "5511…" }] }` or `{ "user_id": "…" }` |
| `GET /v1/groups/{id}/join-requests` · `POST …/approve` · `POST …/reject` | join requests (`join_approval_mode: approval_required`); `{ "join_request_ids": [...] }` → `{ approved \| rejected, failed[] }` |
| `DELETE /v1/groups/{id}` | deletes the group on Meta (`admin` key) |

## Messages

Send with the same `POST /v1/messages`, with the group id in `to`:

```json
{ "connection_id": "conn_...", "to": "grp_...", "type": "text", "text": { "body": "Class confirmed at 9am" } }
```

- There is no 24-hour window check: Meta decides.
- A group that is not `active` → `409` [`group_not_active`](/en/errors#group_not_active).
- A content type Meta does not accept in groups → `422` [`group_message_type_not_supported`](/en/errors#group_message_type_not_supported).

The group conversation has `kind: "group"`. `message.*` events carry `group: { id, external_id, subject }` (or `null` outside groups); on a received message, `contact` is the participant who wrote it.

## Limits

| Limit | Value |
|---|---|
| Participants per group | 8 (above → `422` [`group_participant_limit`](/en/errors#group_participant_limit)) |
| Groups per number | 10,000 (Messajo only warns; Meta decides) |
| Participants per removal | 8 |

## Events

| Type | When |
|---|---|
| `group.created` · `group.create_failed` | Meta finished creating it (or not) |
| `group.settings_updated` | subject, description, photo or join mode changed |
| `group.participants_updated` | someone joined, left or was removed (`joined[]`, `left[]`, `removed[]`) |
| `group.join_requested` | a join request arrived (`join_request`) |
| `group.suspended` · `group.unsuspended` | Meta suspended or released the group |
| `group.deleted` | the group was deleted |

`group.*` events have no `sequence`. Filter by family with `group.*` on the [destination](/en/webhooks/events/).
