Grupos (WABA)

Gestão de grupos via WhatsApp Business (Cloud API): criar, editar, gerenciar participantes e admins, solicitações de entrada, link de convite e envio de mensagens. WABA-only — Baileys e Instagram não expõem a Groups API da Meta.

Base path: /v1/groups · Auth: X-API-Key.

informação

:id aceita dois formatos

Em todas as rotas, :id pode ser o UUID local do grupo (retornado na criação) ou o metaGroupId (id da Meta). O gateway resolve os dois. waIds são números no formato E.164 (ex.: 5511999998888).

---

Objeto Group

{
  "id": "8b1f2c3d-...",                  // UUID do gateway
  "metaGroupId": "120363...@g.us",       // id da Meta
  "phoneId": "5f7b2e1c-...",
  "subject": "Time de Vendas",
  "description": "Avisos internos",
  "joinApprovalMode": "APPROVAL_REQUIRED", // ou AUTO_APPROVE
  "inviteLink": "https://chat.whatsapp.com/...",
  "participants": [
    { "waId": "5511999998888", "joinedAt": "2026-06-04T12:00:00.000Z" }
  ],
  "totalParticipantCount": 1,
  "suspended": false,
  "createdAt": "2026-06-04T12:00:00.000Z"
}

---

Criar grupo

POST /v1/groups

{
  "phoneId": "5f7b2e1c-...",
  "subject": "Time de Vendas",
  "description": "Avisos internos",
  "joinApprovalMode": "APPROVAL_REQUIRED"
}

Campo	Tipo	Obrigatório
phoneId	uuid (WABA)	sim
subject	string (1–128)	sim
description	string (≤2048)	não
joinApprovalMode	AUTO_APPROVE | APPROVAL_REQUIRED	não (default AUTO_APPROVE)

201 Created → objeto Group.

curl -X POST https://wpp.ogmma.com.br/v1/groups \
  -H "X-API-Key: ak_live_..." -H "Content-Type: application/json" \
  -d '{ "phoneId": "5f7b2e1c-...", "subject": "Time de Vendas" }'

---

Listar grupos

GET /v1/groups?phoneId={uuid}

Query	Default	Descrição
phoneId	—	obrigatório (uuid WABA)
includeSuspended	false	inclui grupos suspensos pela Meta
limit	25	1–100
cursor	—	paginação (uuid do último item)

200 → { "items": [Group], "nextCursor": "uuid|null" }.

Detalhe do grupo

GET /v1/groups/:id?refresh=true

refresh=true força re-sincronização com a Meta (participantes, convite). Sem isso, retorna o estado local (mais rápido).

Editar grupo

PATCH /v1/groups/:id

{ "subject": "Novo nome", "description": "...", "joinApprovalMode": "AUTO_APPROVE" }

Todos os campos opcionais. 200 → Group atualizado.

Deletar grupo

DELETE /v1/groups/:id → 204 No Content.

---

Participantes

Adicionar

POST /v1/groups/:id/participants

{ "waIds": ["5511999998888", "5511988887777"] }

Até 50 por chamada. 204. (A Meta pode exigir que o número já tenha conversado com o business.)

Remover

DELETE /v1/groups/:id/participants — mesmo body { "waIds": [...] }. 204.

---

Admins

Promover

POST /v1/groups/:id/admins — body { "waIds": [...] }. 204.

Rebaixar

DELETE /v1/groups/:id/admins — body { "waIds": [...] }. 204.

---

Solicitações de entrada

Quando joinApprovalMode = APPROVAL_REQUIRED, quem entra pelo link fica pendente.

Listar

GET /v1/groups/:id/join-requests?limit=25&after={cursor}

200 → lista de { joinRequestId, waId, requestedAt }.

Aprovar / Rejeitar

POST /v1/groups/:id/join-requests/approve POST /v1/groups/:id/join-requests/reject

{ "joinRequestIds": ["jr_1", "jr_2"] }

Até 100 por chamada.

---

Link de convite

POST /v1/groups/:id/invite-link/reset

Revoga o link atual e gera um novo (invalida o anterior). 200 → { "inviteLink": "https://chat.whatsapp.com/..." }.

O link atual também vem no objeto Group (inviteLink).

---

Sair do grupo (bot)

POST /v1/groups/:id/leave → 204. O número do business sai do grupo.

---

Enviar mensagem no grupo

POST /v1/groups/:id/messages

{
  "type": "text",
  "payload": { "text": { "body": "Olá, time! 👋" } }
}

Campo	Descrição
type	text | image | video | audio | document | sticker | template
payload	objeto no formato da Cloud API correspondente ao type

202 Accepted → { "messageId": "..." }. O envio é enfileirado; o status chega via webhook message:status.

Mensagens 1:1 vs grupo

Para conversas 1:1 use POST /v1/messages (formato canônico do gateway). O endpoint de grupo usa o payload cru da Meta porque dá acesso a recursos específicos de grupo.

---

Eventos de webhook

Mudanças nos grupos chegam no seu webhook (assinados com HMAC):

Evento	Quando
group:lifecycle	grupo criado / deletado / suspenso
group:participants	entrou / saiu / removido
group:settings	subject, descrição ou modo de aprovação mudou
group:status	mudança de status do grupo

Veja o shape em Webhooks.

---

Erros comuns

Código	HTTP	Significado
PHONE_NOT_FOUND	404	phoneId não é um WABA da sua conta
GROUP_NOT_FOUND	404	:id não resolve a um grupo da sua conta

Referência da Meta: Cloud API — Groups.