Listar grupos
GET/connections/{id}/groups
Os grupos de que o número pareado participa, consultados no WhatsApp na hora. A conexão precisa estar open (400 caso contrário), e o provedor dela precisa suportar grupos (501 caso contrário). Escopo necessário: connections:read.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número).
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | groups: cada grupo com jid (o JID do grupo, …@g.us), subject (o nome) e size (quantos participantes). |
| 400 | A conexão não está open (Connection not ready (status: …)): espere o connection.status open ou conecte-a de novo. |
| 400 | FST_ERR_VALIDATIONA requisição não segue o schema da operação (por exemplo, um id que não é um UUID); message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 402 | subscription_inactiveA organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Pague para voltar a usar. |
| 403 | A chave não tem o escopo connections:read; a mensagem de erro cita o escopo que falta. |
| 404 | A conexão não existe ou não é de quem chama: a de outra pessoa responde exatamente como uma que não existe (Connection not found). |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 500 | O WhatsApp não respondeu à consulta dos grupos (Failed to fetch groups): tente de novo. |
| 501 | unsupported_by_providerO provedor da conexão não faz esta operação: o provedor dela não lista grupos. |
| 503 | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de Retry-After e tente de novo.Cabeçalho: Retry-After |
Detalhes
O jid de um grupo (…@g.us) serve como to em POST /connections/{id}/send. Os webhooks group.joined, group.left e group.updated avisam quando o número entra, sai ou quando um grupo muda.
Uma falha inesperada ao consultar o WhatsApp responde 500 (Failed to fetch groups): tente de novo.
Guia: Enviar mensagens
Esta página ajudou? · Atualizado em 28 set 2026