Grupos - Notifique

Grupos no WhatsApp são onde turmas, equipes e comunidades conversam juntos. Pelo Notifique você envia aviso para o grupo inteiro, gerencia participantes e manda link de convite, só na conexão não oficial (número pareado por QR ou link).

Em poucas palavras

Só conexão não oficial, instância oficial (Meta) não envia nem gerencia grupos pela API.
Use a mesma instância que você já pareou para envios 1 a 1.
Chave com escopo whatsapp:groups na integração que precisa.
Envio para grupo = mesma rota de mensagem; só muda o to (...@g.us).

Linha oficial: grupos, participantes e convites não estão disponíveis. Use conexão não oficial ou atendimento 1 a 1 na oficial.

Quando usar

Situação	Usar grupos pela API?
Avisos para várias turmas/equipes (não oficial)	Sim
Automatizar convites e participantes via ERP/CRM	Sim
Instância oficial (Meta)	Não, use 1 a 1 ou mude para não oficial
Só atendimento 1 a 1	Não. Use o WhatsApp normal

Comparação completa: Modos de conexão.

O que você pode fazer

Enviar para o grupo

POST /v1/whatsapp/messages com JID do grupo em to (120363...@g.us).

Listar grupos

GET /v1/whatsapp/instances/{id}/groups com paginação.

Participantes

Listar, adicionar e remover pessoas nos grupos permitidos.

Convites

Enviar link no privado, revogar ou consultar código de convite.

Rotas e campos: referência da API do WhatsApp (seção Grupos).

Antes de começar

Item	Obrigatório
Instância não oficial e ACTIVE	Sim
Escopo `whatsapp:groups` na chave	Sim
Número admin nos grupos que vai mexer	Recomendado

Ainda não pareou? Quick Start WhatsApp (aba não oficial). Escopos: Escopos da API Key. Substitua sk_live_xxxxx pela sua chave e {instanceId} pelo id da instância. Base URL: https://api.notifique.dev.

A API Key pertence a um workspace. Na v1 não envie x-workspace-id.

1. Listar grupos

Retorna a lista paginada de grupos da instância.

GET /v1/whatsapp/instances/{instanceId}/groups?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

Parâmetros opcionais: page (padrão 1), limit (padrão 20, máximo 100). Com grupos carregados

{
  "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 }
}

Ainda sincronizando

{
  "success": true,
  "loading": true,
  "message": "Lista de grupos está sendo carregada. Tente novamente em alguns segundos.",
  "data": [],
  "pagination": { "page": 1, "limit": 20, "total": 0 }
}

Guarde o id (ex.: 120363295648424210@g.us) para os próximos passos.

Participantes do grupo

GET /v1/whatsapp/instances/{instanceId}/groups/120363295648424210@g.us/participants
Authorization: Bearer sk_live_xxxxx

Na URL, codifique @ como %40 se o cliente exigir.

{
  "success": true,
  "data": {
    "participants": [
      { "id": "5511999999999@s.whatsapp.net", "admin": "superadmin" },
      { "id": "5511888888888@s.whatsapp.net", "admin": "admin" }
    ]
  }
}

2. Enviar mensagem no grupo

Mesma rota do WhatsApp individual. Coloque o JID do grupo em to.

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! Aviso enviado pela API."
  }
}

Resposta (202)

{
  "messageIds": ["clxx1..."],
  "status": "QUEUED",
  "scheduledAt": null
}

Vários grupos de uma vez

{
  "instanceId": "clxx...",
  "to": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "type": "text",
  "payload": { "message": "Aviso para vários grupos." }
}

3. Adicionar ou remover participantes

POST /v1/whatsapp/instances/{instanceId}/groups/participants
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

Adicionar

{
  "to": ["120363295648424210@g.us"],
  "action": "add",
  "participants": ["5511888888888", "5511777777777"]
}

Remover

{
  "to": ["120363295648424210@g.us"],
  "action": "remove",
  "participants": ["5511888888888"]
}

Resposta (200), exemplo

{
  "success": true,
  "data": {
    "results": [
      { "groupJid": "120363295648424210@g.us", "success": true, "action": "add", "participantsCount": 2 }
    ]
  }
}

Seu número precisa ser admin do grupo no WhatsApp. Caso contrário, a operação falha.

4. Enviar convite no privado

Manda o link de convite para um ou mais números individuais.

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 o grupo da equipe"
}

{
  "success": true,
  "data": {
    "results": [
      {
        "groupJid": "120363130091228687@g.us",
        "success": true,
        "data": {
          "send": true,
          "inviteUrl": "https://chat.whatsapp.com/EYkW0HWQLJ7CS82xdLIu4i"
        }
      }
    ]
  }
}

5. Revogar ou consultar link de convite

Revogar link atual

POST /v1/whatsapp/instances/{instanceId}/groups/invite/revoke
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "groupJid": "120363295648424210@g.us"
}

Consultar link ou código atuais

GET /v1/whatsapp/instances/{instanceId}/groups/invite-code?groupJid=120363295648424210@g.us
Authorization: Bearer sk_live_xxxxx

{
  "success": true,
  "data": {
    "inviteUrl": "https://chat.whatsapp.com/Gst4H0uNCjMFEwddWjWpm9",
    "inviteCode": "Gst4H0uNCjMFEwddWjWpm9"
  }
}

Limitações importantes

Só não oficial, instância oficial retorna WHATSAPP_GROUPS_UNOFFICIAL_ONLY.
Não cria grupo do zero via API (use grupo existente ou crie no celular antes).
Adicionar pessoas exige admin com permissão no WhatsApp.
Lista pode retornar loading: true na primeira consulta, tente de novo em alguns segundos.
As regras do próprio WhatsApp continuam valendo; a API não substitui permissões do app.

Erros comuns

`code`	O que fazer
`SCOPE_GROUPS_REQUIRED`	Inclua `whatsapp:groups` na chave
`WHATSAPP_GROUPS_UNOFFICIAL_ONLY`	Use instância não oficial
`loading: true` na listagem	Aguarde e chame de novo

Catálogo completo: Respostas de erro.

403: recurso desligado ou sem escopo

Confira se a instância é não oficial e se a chave tem escopo whatsapp:groups.

Falha ao add/remove participante

Verifique se o número da instância é admin do grupo no app WhatsApp.

Próximos passos

Modos de conexão: oficial × não oficial
WhatsApp, Introdução: instância, mensagens e webhooks
Escopos da API Key

​Em poucas palavras

​Quando usar

​O que você pode fazer

Enviar para o grupo

Listar grupos

Participantes

Convites

​Antes de começar

​1. Listar grupos

​Participantes do grupo

​2. Enviar mensagem no grupo

​3. Adicionar ou remover participantes

​4. Enviar convite no privado

​5. Revogar ou consultar link de convite

​Limitações importantes

​Erros comuns

​Próximos passos

Em poucas palavras

Quando usar

O que você pode fazer

Antes de começar

1. Listar grupos

Participantes do grupo

2. Enviar mensagem no grupo

3. Adicionar ou remover participantes

4. Enviar convite no privado

5. Revogar ou consultar link de convite

Limitações importantes

Erros comuns

Próximos passos