Como gerenciar e automatizar grupos do WhatsApp via API

Introdução

Para quem é este guia:

• Desenvolvedores e engenheiros de software que integram recursos do WhatsApp em sistemas de CRM, SaaS ou de negócios personalizados;
• Integradores no-code e especialistas em automação que utilizam Make, Zapier ou n8n;

Casos de uso:

• Criar automaticamente grupos dedicados de suporte ou de integração de clientes;
• Sincronizar listas de participantes de grupos com pipelines de vendas de CRM;
• Transmitir anúncios e alertas transacionais em chats de grupo;
• Conectar chatbots interativos a conversas de grupo;

Pré-requisitos:

• Um número de WhatsApp ativo padrão (aplicativo pessoal ou comercial regular, não WABA oficial);
• Conhecimento básico de solicitações HTTP ou acesso a uma plataforma de automação no-code;

O que você pode fazer com Grupos do WhatsApp via API

• Enviar mensagens para grupos: Envie atualizações, anúncios ou lembretes diretamente para qualquer grupo.
• Criar novos grupos do WhatsApp: Gere grupos automaticamente com base em eventos como onboarding de clientes ou inscrições em cursos.
• Adicionar membros a um grupo: Convide contatos para o grupo de forma programática, sem aprovação manual.
• Promover membros a administradores: Conceda ou remova direitos de admin para participantes selecionados.
• Buscar participantes do grupo: Recupere a lista completa de membros para análise ou sincronização com o CRM.
• Detectar eventos no grupo: Monitore mensagens, entradas e saídas usando webhooks.
• Conectar bots a grupos: Permita que bots leiam e respondam mensagens em grupo conforme a lógica definida.

Por que a API oficial de grupos da Meta falha em produção

Como vincular seu WhatsApp e começar a usar a API

1. 1) Acesse seu painel e abra o Canal Padrão — já está criado para você.
2. 2) No Passo 1, você verá um código QR com instruções.
3. 3) No seu celular, abra WhatsApp → Configurações → Dispositivos conectados → Conectar um dispositivo, então escaneie o QR code.
4. 4) Após conectar, dê um nome ao canal (ex: "Meu Chatbot") para facilitar a identificação.
5. 5) Você será redirecionado para a tela de configurações do canal, pode pular este passo e voltar depois.

Acesse as configurações do WhatsApp no seu celular

Escaneie o QR code no seu WhatsApp

Para conectar seu celular, use o QR code

Sua chave de API

Como enviar mensagens para grupos do WhatsApp via API (com exemplos de código)

1. 1) Primeiro, obtenha o ID do grupo. Use o endpoint GET /groups para buscar uma lista dos seus grupos do WhatsApp com seus identificadores únicos. Para mais detalhes, veja a documentação: Get groups.
2. 2) Com o ID do grupo, você pode enviar uma mensagem. Gere grupos automaticamente com base em eventos como onboarding de clientes. Use o endpoint POST /messages/text, especificando o ID do grupo no parâmetro to e o conteúdo da mensagem em body. Para mais detalhes, veja: Send text message.

1. 1) Ao criar um grupo, o ID será especificado na resposta da API. Abaixo mostramos como fazer isso;
2. 2) Endpoint Get a list of groups;
3. 3) Endpoint Get a list of all chats;

                                            
curl --request POST \
     --url https://gate.whapi.cloud/messages/text \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "to": "[email protected]",
  "body": "Hello, this message was sent via API!"
}
'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://gate.whapi.cloud/messages/text', [
  'body' => '{"to":"[email protected]","body":"Hello, this message was sent via API!"}',
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer YOUR_API_TOKEN',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/messages/text"

payload = {
    "to": "[email protected]",
    "body": "Hello, this message was sent via API!"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://gate.whapi.cloud/messages/text',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer YOUR_API_TOKEN'
  },
  data: {to: '[email protected]', body: 'Hello, this message was sent via API!'}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"to\":\"[email protected]\",\"body\":\"Hello, this message was sent via API!\"}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/messages/text")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer YOUR_API_TOKEN")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;

var options = new RestClientOptions("https://gate.whapi.cloud/messages/text");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer YOUR_API_TOKEN");
request.AddJsonBody("{\"to\":\"[email protected]\",\"body\":\"Hello, this message was sent via API!\"}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

Envio de arquivos de mídia e documentos para grupos

// Send an image or PDF document to a WhatsApp group
const groupId = "[email protected]";
const res = await fetch('https://gate.whapi.cloud/messages/image', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'content-type': 'application/json',
    'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
  },
  body: JSON.stringify({
    to: groupId,
    media: "https://whapi.cloud/assets/img/whapi/logo-text.svg",
    caption: "Welcome to your automated support channel!"
  })
});
const result = await res.json();
console.log("Media message sent:", result);

Como enviar mensagens para grupos usando ferramentas no-code como Make ou n8n

Exemplo de obtenção de ID de grupo no Make (Integromat)

• to: o ID do grupo.
• body: o conteúdo da mensagem

Exemplo de envio de mensagem para grupo via Make

Exemplo de requisição personalizada para enviar mensagem para grupo via Zapier

Como criar um grupo do WhatsApp via API

1. 1) Use o método POST com o endpoint https://gate.whapi.cloud/groups para criar um novo grupo. Forneça o nome do grupo no parâmetro subject e inclua pelo menos um número no parâmetro participants — isso é necessário para criar o grupo com sucesso.
2. 2) Após a criação bem-sucedida, a API retornará um ID do grupo. Você precisará desse identificador para enviar mensagens ao grupo.
3. 3) Para enviar uma mensagem ao grupo, use o método padrão de envio de mensagens. Especifique o ID do grupo no parâmetro to e o conteúdo no body.

                                            
curl --request POST \
     --url https://gate.whapi.cloud/groups \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token' \
     --header 'content-type: application/json' \
     --data '
{
  "participants": [
    "498935516106",
    "4915155985667"
  ],
  "subject": "SEO Common GmbH"
}
'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://gate.whapi.cloud/groups', [
  'body' => '{"participants":["498935516106","4915155985667"],"subject":"SEO Common GmbH"}',
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer Your_Token',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/groups"

payload = {
    "participants": ["498935516106", "4915155985667"],
    "subject": "SEO Common GmbH"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer Your_Token"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://gate.whapi.cloud/groups',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer Your_Token'
  },
  data: {participants: ['498935516106', '4915155985667'], subject: 'SEO Common GmbH'}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"498935516106\",\"4915155985667\"],\"subject\":\"SEO Common GmbH\"}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/groups")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;


var options = new RestClientOptions("https://gate.whapi.cloud/groups");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddJsonBody("{\"participants\":[\"498935516106\",\"4915155985667\"],\"subject\":\"SEO Common GmbH\"}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

Como criar um grupo do WhatsApp usando uma plataforma no-code

{
  "participants": [
    "498935516106",
    "4915155985667"
  ],
  "subject": "SEO Common GmbH"
}

Exemplo de requisição personalizada para criar grupo via Make

Como adicionar participantes a um grupo do WhatsApp

1. 1) Certifique-se de ter o ID do grupo ao qual deseja adicionar membros. Esse é um parâmetro obrigatório. Explicamos acima como obter o ID.
2. 2) Envie uma requisição POST para https://gate.whapi.cloud/groups/{GroupID}/participants para adicionar novos membros. Inclua o ID do grupo na URL e forneça um array de números de telefone dos participantes que deseja adicionar.

Adição direta vs Links de convite

                                            
curl --request POST \
     --url https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token' \
     --header 'content-type: application/json' \
     --data '
{
  "participants": [
    "373983445541",
    "373983445542",
    "373983445543"
  ]
}
'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants', [
  'body' => '{"participants":["373983445541","373983445542","373983445543"]}',
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer Your_Token',
    'content-type' => 'application/json',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants"

payload = { "participants": ["373983445541", "373983445542", "373983445543"] }
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer Your_Token"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer Your_Token'
  },
  data: {participants: ['373983445541', '373983445542', '373983445543']}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"373983445541\",\"373983445542\",\"373983445543\"]}");
Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;


var options = new RestClientOptions("https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddJsonBody("{\"participants\":[\"373983445541\",\"373983445542\",\"373983445543\"]}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

Como adicionar participantes a um grupo usando ferramentas no-code

{
  "participants": [
    "373983445541",
    "373983445542",
    "373983445543"
  ]
}

Automação no-code no mundo real: criação automática de grupos de suporte (Make e n8n)

1. Criar o grupo: envie uma solicitação POST /groups com um assunto como "Suporte ao Cliente: Nome da Empresa" e inclua seu número de bot principal.
2. Adicionar participantes: chame POST /groups/{groupId}/participants para adicionar o número de telefone do cliente e seu gerente de contas designado.
3. Enviar mensagem de boas-vindas: envie uma solicitação POST /messages/image ou POST /messages/text para entregar um PDF de integração ou um banner de boas-vindas.

Como buscar participantes de um grupo do WhatsApp via API

1. 1) Certifique-se de ser membro do grupo que deseja acessar. Sem isso, não será possível obter a lista de participantes.
2. 2) Use o método da API Get Groups para buscar todos os grupos associados à sua conta do WhatsApp. Se já souber o ID do grupo desejado, consulte diretamente usando o endpoint Get group.
3. 3) A resposta incluirá um array de objetos de grupo, cada um contendo informações como o ID, nome e um campo participants com a lista de membros. Exemplo de resposta:

{
  "id": "[email protected]",
  "name": "A group of researchers",
  "participants": [
    { "id": "972558557032", "rank": "member" },
    { "id": "14409416972", "rank": "creator" },
    { "id": "905589461962", "rank": "member" }
  ]
}

                                            
curl --request GET \
     --url 'https://gate.whapi.cloud/groups?count=100' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Your_Token'

                                            
// composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://gate.whapi.cloud/groups?count=100', [
  'headers' => [
    'accept' => 'application/json',
    'authorization' => 'Bearer Your_Token',
  ],
]);

echo $response->getBody();

                                            
# python -m pip install requests

import requests

url = "https://gate.whapi.cloud/groups?count=100"

headers = {
    "accept": "application/json",
    "authorization": "Bearer Your_Token"
}

response = requests.get(url, headers=headers)

print(response.text)

                                            
// npm install axios --save

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://gate.whapi.cloud/groups?count=100',
  headers: {accept: 'application/json', authorization: 'Bearer Your_Token'}
};

axios
  .request(options)
  .then(res => console.log(res.data))
  .catch(err => console.error(err));

                                            
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://gate.whapi.cloud/groups?count=100")
  .get()
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer Your_Token")
  .build();

Response response = client.newCall(request).execute();

                                            
//dotnet add package RestSharp

using RestSharp;

var options = new RestClientOptions("https://gate.whapi.cloud/groups?count=100");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

Como obter membros de um grupo do WhatsApp via no-code

Como conectar um bot a um grupo do WhatsApp

• Criar um bot do WhatsApp em Node.js;
• Criar um bot do WhatsApp em Python;
• Criar um bot do WhatsApp em PHP;
• Criar um bot do WhatsApp em Java;

Dicas, limitações e melhores práticas

• Não adicione usuários a grupos sem consentimento. Respeite a privacidade e evite convites não solicitados;
• Evite enviar spam ou conteúdo indesejado, pois sua conta pode ser marcada ou banida permanentemente;
• A Whapi.Cloud não impõe limites rígidos de taxa de API em canais pagos, mas o WhatsApp pode sinalizar contas que enviam mais de ~20 mensagens por minuto sem histórico de aquecimento. Use ritmo semelhante ao humano e atrasos aleatórios de 1.5 a 3.5 segundos entre as ações.

// PATCH https://gate.whapi.cloud/groups/{groupId}/admins
const groupId = "[email protected]";
const res = await fetch(`https://gate.whapi.cloud/groups/${groupId}/admins`, {
  method: 'PATCH',
  headers: {
    'accept': 'application/json',
    'content-type': 'application/json',
    'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
  },
  body: JSON.stringify({
    participants: ["4915155985667"]
  })
});
const status = await res.json();
console.log("Admin promotion status:", status);

Resolução de problemas

Bot não responde a mensagens recebidas

Bot envia mensagens sem parar

Retornos de chamada de webhook e problemas comuns de automação de grupos

• Loop de envio do bot: certifique-se de que seu arquivo de código verifique o sinalizador from_me nos payloads recebidos para evitar loops de resposta infinitos.
• Erro de permissão negada: isso ocorre ao tentar adicionar um participante enquanto a conta do bot não é administradora do grupo. Verifique a classificação do bot via GET /groups/{GroupID}.
• Falta de números na lista: a sincronização de metadatos do grupo leva até 15 segundos. Se você chamar a API imediatamente após a criação, os números de telefone dos participantes podem levar alguns momentos para serem resolvidos.

Não consegue adicionar um usuário ao grupo?

• Você deve ser administrador do grupo. Apenas admins podem adicionar novos membros.
• O usuário pode ter restrições de convite em suas configurações de privacidade. Se for o caso, não pode ser adicionado automaticamente via API.
• O grupo pode ter atingido o limite máximo de 1024 participantes. Nesse caso, remova membros inativos ou considere criar um novo grupo.
• As políticas anti-spam do WhatsApp podem bloquear a adição de certos números aos grupos — especialmente se o contato não estiver salvo na sua agenda ou não tiver interagido com você. Para reduzir esse risco, recomendamos fortemente adicionar programaticamente o contato à sua lista primeiro usando nossa API de Adição de Contatos.

Mensagem não entregue?

• Verifique o ID do grupo — IDs incorretos ou expirados causarão falha na entrega.
• Se a mensagem for enviada mas não aparecer no grupo, revise o formato. Por exemplo, grupos do WhatsApp podem não exibir certos tipos de conteúdo, como imagens webp ou botões interativos.

Permissão negada?

• Seu número não é reconhecido como admin do grupo.
• A API pode não ter sincronizado corretamente seu status de admin ou número. Nesse caso, tente reautorizar seu canal API para atualizar permissões e metadados.

Membros do grupo não exibidos?

O que significa @lid na lista de participantes?

// GET https://gate.whapi.cloud/contacts/ids/{contactLid}
const contactLid = "1524746986546@lid";
const res = await fetch(`https://gate.whapi.cloud/contacts/ids/${contactLid}`, {
  method: 'GET',
  headers: {
    'accept': 'application/json',
    'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
  }
});
const { phone } = await res.json();
console.log("Resolved JID phone number:", phone);

Deploy e uso de servidores

Firebase

AWS (Amazon Web Services)

Heroku

Resumo e próximos passos