Skip to main content

​
O fluxo principal (visão geral)

  1. Instância ACTIVE + recurso grupos ativo no workspace + API Key com whatsapp:groups.
  2. Listar grupos → copiar o JID (...@g.us).
  3. Enviar com POST /v1/whatsapp/messages usando o JID em to (mesma rota do chat privado).
Participantes e convites usam rotas dedicadas — veja a sequência numérica abaixo.

​
Pré-requisitos

  • API Key com escopo whatsapp:groups.
  • Workspace com Recursos de grupos (experimental) ativados (Settings → Recursos experimentais).
  • Instância WhatsApp conectada (status ACTIVE) e que participe de pelo menos um grupo.
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx

​
1. Listar grupos

Obtenha todos os grupos da instância de forma paginada. A API usa cache e responde sempre antes do timeout: se os grupos ainda estiverem sendo carregados, a resposta vem com loading: true e mensagem para tentar em breve. A listagem não inclui participantes; use a rota da seção 1.1 para obter os participantes de um grupo. Request 
GET /v1/whatsapp/instances/{instanceId}/groups?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Query opcionais: page (padrão 1), limit (padrão 20, máx. 100). Response (200) — com dados em cache 
{
  "success": true,
  "data": [
    {
      "id": "120363295648424210@g.us",
      "name": "Meu Grupo",
      "participantsCount": 5,
      "owner": "5511999999999@s.whatsapp.net",
      "creation": 1699000000
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 5 }
}
Response (200) — carregando (tente de novo em alguns segundos) 
{
  "success": true,
  "loading": true,
  "message": "Lista de grupos está sendo carregada. Tente novamente em alguns segundos.",
  "data": [],
  "pagination": { "page": 1, "limit": 20, "total": 0 }
}
Anote o id (JID) do grupo, por exemplo: 120363295648424210@g.us.

​
1.1. Listar participantes de um grupo

Para obter a lista de participantes de um grupo, use a rota específica passando o id do grupo (JID completo ou só o número). Request 
GET /v1/whatsapp/instances/{instanceId}/groups/120363295648424210@g.us/participants
Authorization: Bearer sk_live_xxxxx
(O groupId na URL pode ser 120363295648424210@g.us ou 120363295648424210; use encoding adequado para @ na URL, ex.: %40.) Response (200) 
{
  "success": true,
  "data": {
    "participants": [
      { "id": "5511999999999@s.whatsapp.net", "admin": "superadmin" },
      { "id": "5511888888888@s.whatsapp.net", "admin": "admin" }
    ]
  }
}

​
2. Enviar mensagem para um grupo

Use a rota oficial de mensagens POST /v1/whatsapp/messages. Para grupos, preencha to com um ou mais JIDs de grupo (ex.: 120363295648424210@g.us). O restante do body é igual ao envio para números: instanceId, type, payload; opcionalmente schedule.sendAt e options. Request — texto para um grupo 
POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "clxx...",
  "to": ["120363295648424210@g.us"],
  "type": "text",
  "payload": {
    "message": "Olá, grupo! Mensagem enviada pela API."
  }
}
Response (202) 
{
  "messageIds": ["clxx1..."],
  "status": "QUEUED",
  "scheduledAt": null
}
Enviar para vários grupos — inclua mais JIDs em to: 
{
  "instanceId": "clxx...",
  "to": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "type": "text",
  "payload": { "message": "Broadcast para vários grupos." }
}
Agendar envio — use schedule.sendAt em ISO 8601: 
{
  "instanceId": "clxx...",
  "to": ["120363295648424210@g.us"],
  "type": "text",
  "payload": { "message": "Lembrete agendado." },
  "schedule": { "sendAt": "2025-12-31T14:00:00.000Z" }
}
Tipos suportados: text, image, video, audio, document, location, contact, buttons — o payload segue o mesmo formato do envio para números.

​
3. Adicionar ou remover participantes

Use o campo to (array de JIDs de grupo), no mesmo padrão das outras rotas. Assim você pode adicionar ou remover participantes em um ou vários grupos na mesma requisição. action: add ou remove; participants: números com DDI ou JIDs. Request — adicionar em um grupo 
POST /v1/whatsapp/instances/{instanceId}/groups/participants
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "to": ["120363295648424210@g.us"],
  "action": "add",
  "participants": ["5511888888888", "5511777777777"]
}
Request — adicionar o mesmo participante em vários grupos 
{
  "to": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "action": "add",
  "participants": ["5511888888888"]
}
Request — remover participantes 
{
  "to": ["120363295648424210@g.us"],
  "action": "remove",
  "participants": ["5511888888888"]
}
Response (200) — data.results é um array com um item por grupo. Em sucesso: groupJid, success: true, action (add|remove) e participantsCount. Em falha: groupJid, success: false e error (mensagem objetiva). 
{
  "success": true,
  "data": {
    "results": [
      { "groupJid": "120363295648424210@g.us", "success": true, "action": "add", "participantsCount": 2 },
      { "groupJid": "120363295648424211@g.us", "success": true, "action": "add", "participantsCount": 2 }
    ]
  }
}
Se algum grupo falhar, esse item terá success: false e error com a mensagem (ex.: “Grupo não encontrado ou a instância não tem acesso a ele.”).
Envie o link de convite de um ou mais grupos para um ou mais números. Use groups (array de JIDs de grupo) e to (array de números com DDI que recebem os links). Opcionalmente description (texto que acompanha o convite). Assim você pode enviar o link de vários grupos para o mesmo contato em uma requisição. Request — um grupo 
POST /v1/whatsapp/instances/{instanceId}/groups/invite
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "groups": ["120363295648424210@g.us"],
  "to": ["5511999999999"],
  "description": "Convite para entrar no grupo da equipe"
}
Request — vários grupos para um contato 
{
  "groups": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "to": ["5511999999999"],
  "description": "Links dos grupos"
}
Response (200) — data.results com um item por grupo. Em sucesso, cada item traz groupJid, success: true e data com send (boolean) e inviteUrl (URL do convite enviada aos números). Em falha: success: false e error. 
{
  "success": true,
  "data": {
    "results": [
      { "groupJid": "120363130091228687@g.us", "success": true, "data": { "send": true, "inviteUrl": "https://chat.whatsapp.com/EYkW0HWQLJ7CS82xdLIu4i" } },
      { "groupJid": "120363048720182344@g.us", "success": true, "data": { "send": true, "inviteUrl": "https://chat.whatsapp.com/Gst4H0uNCjMFEwddWjWpm9" } }
    ]
  }
}
Se algum grupo falhar, esse item terá success: false e error com a mensagem.
Revoga o link de convite atual do grupo. O link antigo deixa de funcionar; um novo pode ser obtido pelo endpoint de código de convite (próximo passo). Request 
POST /v1/whatsapp/instances/{instanceId}/groups/invite/revoke
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "groupJid": "120363295648424210@g.us"
}
Response (200) — link revogado.

​
6. Buscar código/URL de convite

Retorna o código ou URL de convite atual do grupo. Passe o groupJid na query. Request 
GET /v1/whatsapp/instances/{instanceId}/groups/invite-code?groupJid=120363295648424210@g.us
Authorization: Bearer sk_live_xxxxx
Response (200) — data contém a URL e o código do convite atual do grupo. 
{
  "success": true,
  "data": {
    "inviteUrl": "https://chat.whatsapp.com/Gst4H0uNCjMFEwddWjWpm9",
    "inviteCode": "Gst4H0uNCjMFEwddWjWpm9"
  }
}

​
Resumo do fluxo

  1. GET /v1/whatsapp/instances/{instanceId}/groups?page=1&limit=20 → listar grupos (paginado, cache); resposta pode vir com loading: true — tente de novo em breve.
  2. GET /v1/whatsapp/instances/{instanceId}/groups/{groupId}/participants → listar participantes de um grupo.
  3. POST /v1/whatsapp/messages → enviar mensagem para um ou mais grupos (to = array de JIDs, type, payload).
  4. POST /v1/whatsapp/instances/{instanceId}/groups/participants → adicionar/remover participantes em um ou mais grupos (to = array de JIDs, action, participants).
  5. POST /v1/whatsapp/instances/{instanceId}/groups/invite → enviar link de convite (to = números).
  6. POST /v1/whatsapp/instances/{instanceId}/groups/invite/revoke → revogar o link atual.
  7. GET /v1/whatsapp/instances/{instanceId}/groups/invite-code?groupJid=... → obter o código/URL de convite.

​
Referências

  • Escopos: A API Key precisa do escopo whatsapp:groups. Veja a documentação de escopos da API Key.
  • Erros 403: Se o workspace não tiver recursos de grupos ativados ou a chave não tiver o escopo, a API retorna 403 com código GROUP_FEATURES_DISABLED ou mensagem de escopo ausente.