Grupos

Hub persiste o estado de cada grupo onde o chip esta participando: subject, description, lista de participantes (com flag de admin), foto cacheada. Atualiza via groups.upsert/groups.update/group-participants.update do Baileys.

Auth. Aceita admin key OU Bearer App com app_chip_access.canReceive=true no chip dono. Sem acesso → 403 groups-access-denied.

`GET /v1/chips/:chipId/groups`

Lista todos os grupos do chip. Sem paginacao — chips reais raramente passam de algumas dezenas de grupos.

GET /v1/chips/{chipId}/groups
Authorization: Bearer APP_KEY

Resposta 200

{
  "data": [
    {
      "chip_id": "01HZTQCHIP...",
      "group_jid": "120363xxx@g.us",
      "subject": "Familia",
      "participants_count": 8,
      "participants": [
        { "jid": "5511988887777@s.whatsapp.net", "admin": "superadmin" },
        { "jid": "5511999998888@s.whatsapp.net", "admin": null }
      ],
      "photo_media_id": "01HZTQPHOTO...",
      "last_synced_at": "2026-05-03T10:00:00.000Z",
      "sync_error": null
    }
  ]
}

Campo	Notas
`participants[i].admin`	`'admin'` \| `'superadmin'` (criador) \| `null` (membro normal)
`photo_media_id`	baixe via `GET /v1/media/:id` (mesma logica de mensagens/contatos)
`last_synced_at`	quando foi a ultima atualizacao via Baileys
`sync_error`	nao-null = ultimo sync falhou (Baileys nao retornou metadata)

`GET /v1/chips/:chipId/groups/:groupJid`

Detalhe de 1 grupo. Mesmo schema, sem o wrapper data.

O groupJid no path precisa estar URL-encoded (120363xxx%40g.us) por causa do @.

Erros

403 groups-access-denied — Bearer App sem canReceive no chip
404 chip-not-found — chip nao existe ou e de outro tenant
404 group-not-found — chip nao esta nesse grupo (nunca foi adicionado ou ja saiu)

Por que isso existe?

A integradora ja recebe webhook group.created/group.updated/group.member_* em tempo real. Mas:

Bootstrap: app nova precisa popular o estado existente sem reprocessar todo o historico de eventos
Recuperacao de sync perdido: webhook caiu, integradora perdeu eventos — esse REST permite reconciliar
Renderizar UI/inbox: precisa de subject + foto pra exibir nome de grupo em chats

Pra evolucao em tempo real, continue ouvindo os webhooks. Use REST so pra bootstrap/reconcile.