Introdução
Para quem é este guia:
- Para desenvolvedores que integram recursos do WhatsApp em sistemas corporativos;
- Para usuários low-code que automatizam fluxos de trabalho com Make, Zapier, N8N, IFTTT ou Pabbly;
Casos de uso:
- Criação automática de grupos para novos clientes ou eventos;
- Adição/remoção de membros com base em atualizações do CRM;
- Envio de anúncios ou lembretes em grupos;
- Conexão de bots de IA a conversas em grupo do WhatsApp;
Pré-requisitos:
- Um número cadastrado no WhatsApp comum (não na API Business da Meta);
- Conhecimento básico de programação ou acesso a uma plataforma low-code como Make;
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.
Como vincular seu WhatsApp e começar a usar a API
- 1) Acesse seu painel e abra o Canal Padrão — já está criado para você.
- 2) No Passo 1, você verá um código QR com instruções.
- 3) No seu celular, abra WhatsApp → Configurações → Dispositivos conectados → Conectar um dispositivo, então escaneie o QR code.
- 4) Após conectar, dê um nome ao canal (ex: "Meu Chatbot") para facilitar a identificação.
- 5) Você será redirecionado para a tela de configurações do canal, pode pular este passo e voltar depois.




Como enviar mensagens para grupos do WhatsApp via API (com exemplos de código)
- 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) 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âmetroto
e o conteúdo da mensagem embody
. Para mais detalhes, veja: Send text message.
Você pode obter o ID do grupo usando o endpoint Get groups ou verificando conversas recentes pelo endpoint chats.
- 1) Ao criar um grupo, o ID será especificado na resposta da API. Abaixo mostramos como fazer isso;
- 2) Endpoint Get a list of groups;
- 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);
Como enviar mensagens para grupos usando ferramentas no-code como Make ou n8n
GET https://gate.whapi.cloud/groups

POST https://gate.whapi.cloud/messages/text
to
: o ID do grupo.body
: o conteúdo da mensagem


Como criar um grupo do WhatsApp via API
- 1) Use o método
POST
com o endpointhttps://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) Após a criação bem-sucedida, a API retornará um ID do grupo. Você precisará desse identificador para enviar mensagens ao grupo.
- 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 nobody
.
participants
para garantir a criação bem-sucedida.
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
POST
para https://gate.whapi.cloud/groups
com o subject
(nome do grupo) e participants
(array de números).{
"participants": [
"498935516106",
"4915155985667"
],
"subject": "SEO Common GmbH"
}

Como adicionar participantes a um grupo do WhatsApp
- 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) Envie uma requisição
POST
parahttps://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.
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
https://gate.whapi.cloud/groups/[email protected]/participants
.@
por %40
.{
"participants": [
"373983445541",
"373983445542",
"373983445543"
]
}
Como buscar participantes de um grupo do WhatsApp via API
- 1) Certifique-se de ser membro do grupo que deseja acessar. Sem isso, não será possível obter a lista de participantes.
- 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) 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
GET
para https://gate.whapi.cloud/groups
para buscar todos os grupos dos quais você é membro, com detalhes de cada grupo — incluindo informações dos participantes.GET https://gate.whapi.cloud/groups/{GroupID}
para buscar dados de um grupo específico.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;
chat_id
, que terá o formato [email protected]
(diferente de um número de telefone em chats privados). O campo from
indicará o número do remetente dentro do grupo.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;
- Embora não haja limites rígidos, recomendamos imitar o comportamento humano: não crie dezenas de grupos nem envie muitas mensagens por segundo. Adicione pausas e use atrasos razoáveis entre ações ao automatizar tarefas em grupo;
Promote to Group Admin
. Para detalhes de implementação, veja a documentação aqui.Resolução de problemas
Bot não responde a mensagens recebidas
- Certifique-se de que você está enviando mensagens para o número em que o bot está ativo, de outro telefone. O bot não poderá responder mensagens enviadas do mesmo número.
- Se o bot não responder a mensagens de outros números, verifique o funcionamento dos webhooks. Use serviços de simulação de webhooks, como o Webhook.site, para confirmar como as solicitações de callback estão chegando. Depois, verifique se o caminho corresponde ao configurado por você. Além disso, certifique-se de que seu servidor responde com 200Ok.
Bot envia mensagens sem parar
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 certos números — especialmente se o contato não estiver salvo ou não tiver interagido com você. Você pode tentar sincronizar contatos via nossa integração com Google Contacts, mas mesmo assim pode não funcionar devido a filtros internos do WhatsApp.
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?
GET /groups
ou GET /group
, os dados do grupo entram na fila de sincronização.O que significa @lid na lista de participantes?
Deploy e uso de servidores
Firebase
- Crie um projeto no Firebase Console;
- Instale o Firebase CLI, seguindo as instruções;
- Initialize o Firebase no diretório do seu projeto usando o comando firebase init;
- Implante seu bot usando o comando firebase deploy --only functions.
AWS (Amazon Web Services)
- Registre-se ou entre no Console de Gerenciamento da AWS;
- Crie uma nova função Lambda através do console da AWS, escolhendo o API Gateway como gatilho;
- Carregue o código do seu bot na função Lambda;
- Configure o API Gateway para interação do seu bot com o mundo externo.
Heroku
- Crie uma conta no Heroku;
- Instale o Heroku CLI e faça login;
- Crie um novo aplicativo no Heroku através do console ou usando o comando heroku create;
- Associe seu repositório Git ao Heroku e faça o deploy usando os comandos git push heroku master;
- Configure o URL do webhook fornecido pelo Heroku.