# Grupos en WhatsApp

> Crear y administrar grupos con la Groups API, enviar y recibir mensajes de grupo y los eventos group.*.

La [Groups API](https://developers.facebook.com/docs/whatsapp/cloud-api/groups) de Meta permite que un número en modo **solo API** cree y administre grupos pequeños. En Messajo existe **solo por la API**: el panel no tiene pantalla de grupos.

## Antes de empezar

- Conexión de WhatsApp **solo API**. En coexistencia, `422` [`group_not_supported`](/es/errors#group_not_supported).
- En el webhook de la app de Meta, los campos `group_lifecycle_update`, `group_participants_update`, `group_settings_update` y `group_status_update` suscritos.
- Clave con `send` para crear, editar y moderar, `read` para leer y `admin` para borrar.

## Crear

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

El grupo nace `creating` (`grp_…`). Meta lo crea en segundo plano y avisa por webhook: salió bien → `active` con el `invite_link` y el evento `group.created`; falló → `failed` y `group.create_failed` con el motivo. `subject` tiene hasta 128 caracteres y `description` hasta 2048.

| Estado | Qué significa |
|---|---|
| `creating` | esperando a Meta |
| `active` | listo para mensajes |
| `suspended` | suspendido por Meta |
| `deleting` · `deleted` | borrado |
| `failed` | Meta no lo creó |

## Administrar

| Llamada | Qué hace |
|---|---|
| `GET /v1/groups` · `GET /v1/groups/{id}` | lista y lee (asunto, descripción, participantes, estado) |
| `PATCH /v1/groups/{id}` | cambia asunto y descripción; en `multipart/form-data`, el campo `picture` cambia la foto (JPEG cuadrado, ≥ 192 px, hasta 5 MiB) |
| `GET /v1/groups/{id}/invite-link` · `POST …/invite-link/reset` | lee o genera un enlace de invitación nuevo (el anterior deja de valer) |
| `POST /v1/groups/{id}/participants/remove` | `{ "participants": [{ "wa_id": "5511…" }] }` o `{ "user_id": "…" }` |
| `GET /v1/groups/{id}/join-requests` · `POST …/approve` · `POST …/reject` | solicitudes de ingreso (`join_approval_mode: approval_required`); `{ "join_request_ids": [...] }` → `{ approved \| rejected, failed[] }` |
| `DELETE /v1/groups/{id}` | borra el grupo en Meta (clave `admin`) |

## Mensajes

Envía con el mismo `POST /v1/messages`, con el id del grupo en `to`:

```json
{ "connection_id": "conn_...", "to": "grp_...", "type": "text", "text": { "body": "Clase confirmada a las 9h" } }
```

- No hay control de ventana de 24 h: decide Meta.
- Grupo que no está `active` → `409` [`group_not_active`](/es/errors#group_not_active).
- Tipo de contenido que Meta no acepta en grupos → `422` [`group_message_type_not_supported`](/es/errors#group_message_type_not_supported).

La conversación del grupo tiene `kind: "group"`. Los eventos `message.*` traen `group: { id, external_id, subject }` (o `null` fuera de grupos); en un mensaje recibido, el `contact` es el participante que escribió.

## Límites

| Límite | Valor |
|---|---|
| Participantes por grupo | 8 (por encima → `422` [`group_participant_limit`](/es/errors#group_participant_limit)) |
| Grupos por número | 10.000 (Messajo solo avisa; decide Meta) |
| Participantes por remoción | 8 |

## Eventos

| Tipo | Cuándo |
|---|---|
| `group.created` · `group.create_failed` | Meta terminó de crearlo (o no) |
| `group.settings_updated` | cambiaron asunto, descripción, foto o modo de ingreso |
| `group.participants_updated` | alguien entró, salió o fue removido (`joined[]`, `left[]`, `removed[]`) |
| `group.join_requested` | llegó una solicitud de ingreso (`join_request`) |
| `group.suspended` · `group.unsuspended` | Meta suspendió o liberó el grupo |
| `group.deleted` | el grupo fue borrado |

Los eventos `group.*` no tienen `sequence`. Filtra por familia con `group.*` en el [destino](/es/webhooks/events/).
