Skip to main content
Esta página é para quem já usa WhatsApp pelo Notifique e quer automatizar grupos (avisos em massa, lista de quem está no grupo, convites). Se você ainda não pareou um número, comece pela introdução do WhatsApp e pelo Quick Start do canal principal.

​
Antes de começar

Você vai precisar de:
  • Instância ativa — o mesmo número conectado por QR, status “ok” para enviar.
  • Grupos (experimental) ligado no workspace (em geral em Configurações → recursos experimentais).
  • Chave de API com escopo whatsapp:groups. A chave pertence a um workspace — a API resolve sozinha.
  • URL base da API (exemplos: https://api.notifique.dev).
Substitua sk_live_xxxxx pela sua chave e {instanceId} pelo id da instância.

​
O caminho em três passos

  1. Listar grupos da instância e anotar o id do grupo (termina em @g.us).
  2. Enviar mensagem usando a mesma rota de sempre, com esse id no destino.
  3. Para participantes e convites, use as rotas específicas abaixo.

​
1. Listar grupos

A lista vem paginada e pode usar cache: às vezes a resposta diz que ainda está carregando — espere alguns segundos e chame de novo. A listagem não traz a lista de participantes; isso é o passo 1.1. Pedido 
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). Resposta (200) — quando já há dados 
{
  "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 }
}
Resposta (200) — ainda carregando 
{
  "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 do grupo (ex.: 120363295648424210@g.us) para os próximos passos.

​
1.1. Quem está no grupo

Pedido 
GET /v1/whatsapp/instances/{instanceId}/groups/120363295648424210@g.us/participants
Authorization: Bearer sk_live_xxxxx
Na URL, o @ pode precisar ser codificado como %40. Resposta (200) — exemplo 
{
  "success": true,
  "data": {
    "participants": [
      { "id": "5511999999999@s.whatsapp.net", "admin": "superadmin" },
      { "id": "5511888888888@s.whatsapp.net", "admin": "admin" }
    ]
  }
}

​
2. Enviar mensagem para o grupo

É o mesmo envio do WhatsApp no Notifique: POST /v1/whatsapp/messages. A diferença é colocar no to o id do grupo (...@g.us) em vez do número da pessoa. Agendamento e idempotência seguem as mesmas regras do canal principal. Pedido — 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."
  }
}
Resposta (202) — exemplo 
{
  "messageIds": ["clxx1..."],
  "status": "QUEUED",
  "scheduledAt": null
}
Vários grupos de uma vez — mais itens em to: 
{
  "instanceId": "clxx...",
  "to": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "type": "text",
  "payload": { "message": "Broadcast para vários grupos." }
}
Agendar — campo schedule com data/hora em formato internacional (ISO 8601), como no Quick Start do WhatsApp principal. Tipos de mensagem (text, image, video, etc.) seguem o mesmo formato do envio para número; veja o OpenAPI do canal.

​
3. Incluir ou tirar pessoas

Uma chamada pode valer para um ou vários grupos (lista em to). action: add ou remove; participants: números com DDI ou identificadores no formato do WhatsApp. Pedido — 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"]
}
Mesma pessoa em vários grupos 
{
  "to": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "action": "add",
  "participants": ["5511888888888"]
}
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 },
      { "groupJid": "120363295648424211@g.us", "success": true, "action": "add", "participantsCount": 2 }
    ]
  }
}
Cada item em results fala de um grupo. Se algo der errado num grupo, aquele item vem com success: false e uma error explicando.
Útil para alguém entrar sem você colar link na mão: você diz quais grupos (groups) e quem recebe (to — números com DDI). Opcional: description (texto que acompanha o convite). Pedido — 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"
}
Vários grupos para o mesmo contato 
{
  "groups": ["120363295648424210@g.us", "120363295648424211@g.us"],
  "to": ["5511999999999"],
  "description": "Links dos grupos"
}
Resposta (200) — exemplo 
{
  "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" } }
    ]
  }
}
O link antigo deixa de funcionar; depois você pode pedir um código novo (passo 6). Pedido 
POST /v1/whatsapp/instances/{instanceId}/groups/invite/revoke
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "groupJid": "120363295648424210@g.us"
}
Pedido 
GET /v1/whatsapp/instances/{instanceId}/groups/invite-code?groupJid=120363295648424210@g.us
Authorization: Bearer sk_live_xxxxx
Resposta (200) — exemplo 
{
  "success": true,
  "data": {
    "inviteUrl": "https://chat.whatsapp.com/Gst4H0uNCjMFEwddWjWpm9",
    "inviteCode": "Gst4H0uNCjMFEwddWjWpm9"
  }
}

​
Continuar

Se a API responder 403 com ideia de recurso desligado ou escopo em falta, confira de novo a seção Antes de começar acima.