# Grupos no WhatsApp

> Criar e administrar grupos pela Groups API, mandar e receber mensagens de grupo e os eventos group.*.

A [Groups API](https://developers.facebook.com/docs/whatsapp/cloud-api/groups) da Meta deixa um número em modo **só API** criar e administrar grupos pequenos. No Messajo ela existe **só pela API**: o painel não tem tela de grupos.

## Antes de começar

- Conexão de WhatsApp **só API**. Na coexistência, `422` [`group_not_supported`](/errors#group_not_supported).
- No webhook do app da Meta, os campos `group_lifecycle_update`, `group_participants_update`, `group_settings_update` e `group_status_update` assinados.
- Chave com `send` para criar, editar e moderar, `read` para ler e `admin` para apagar.

## Criar

```bash
curl https://api.messajo.com/v1/groups \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_...",
    "subject": "Turma de sábado",
    "description": "Avisos da turma",
    "join_approval_mode": "approval_required"
  }'
```

O grupo nasce `creating` (`grp_…`). A Meta cria em segundo plano e avisa por webhook: deu certo → `active` com o `invite_link` e o evento `group.created`; falhou → `failed` e `group.create_failed` com o motivo. `subject` vai até 128 caracteres e `description` até 2048.

| Status | O que quer dizer |
|---|---|
| `creating` | esperando a Meta |
| `active` | pronto para mensagens |
| `suspended` | suspenso pela Meta |
| `deleting` · `deleted` | apagado |
| `failed` | a Meta não criou |

## Administrar

| Chamada | O que faz |
|---|---|
| `GET /v1/groups` · `GET /v1/groups/{id}` | lista e lê (assunto, descrição, participantes, status) |
| `PATCH /v1/groups/{id}` | troca assunto e descrição; em `multipart/form-data`, o campo `picture` troca a foto (JPEG quadrado, ≥ 192 px, até 5 MiB) |
| `GET /v1/groups/{id}/invite-link` · `POST …/invite-link/reset` | lê ou gera um link de convite novo (o antigo deixa de valer) |
| `POST /v1/groups/{id}/participants/remove` | `{ "participants": [{ "wa_id": "5511…" }] }` ou `{ "user_id": "…" }` |
| `GET /v1/groups/{id}/join-requests` · `POST …/approve` · `POST …/reject` | pedidos de entrada (`join_approval_mode: approval_required`); `{ "join_request_ids": [...] }` → `{ approved \| rejected, failed[] }` |
| `DELETE /v1/groups/{id}` | apaga o grupo na Meta (chave `admin`) |

## Mensagens

Mande com o mesmo `POST /v1/messages`, com o id do grupo em `to`:

```json
{ "connection_id": "conn_...", "to": "grp_...", "type": "text", "text": { "body": "Aula confirmada às 9h" } }
```

- Não há checagem de janela de 24 h: a Meta decide.
- Grupo que não está `active` → `409` [`group_not_active`](/errors#group_not_active).
- Tipo de conteúdo que a Meta não aceita em grupo → `422` [`group_message_type_not_supported`](/errors#group_message_type_not_supported).

A conversa do grupo tem `kind: "group"`. Os eventos `message.*` trazem `group: { id, external_id, subject }` (ou `null` fora de grupo); numa mensagem recebida, o `contact` é o participante que escreveu.

## Limites

| Limite | Valor |
|---|---|
| Participantes por grupo | 8 (acima → `422` [`group_participant_limit`](/errors#group_participant_limit)) |
| Grupos por número | 10.000 (o Messajo só avisa; a Meta decide) |
| Participantes por remoção | 8 |

## Eventos

| Tipo | Quando |
|---|---|
| `group.created` · `group.create_failed` | a Meta terminou de criar (ou não) |
| `group.settings_updated` | assunto, descrição, foto ou modo de entrada mudaram |
| `group.participants_updated` | alguém entrou, saiu ou foi removido (`joined[]`, `left[]`, `removed[]`) |
| `group.join_requested` | chegou um pedido de entrada (`join_request`) |
| `group.suspended` · `group.unsuspended` | a Meta suspendeu ou liberou o grupo |
| `group.deleted` | o grupo foi apagado |

Os eventos `group.*` não têm `sequence`. Filtre por família com `group.*` no [destino](/webhooks/events/).
