Pule o boilerplate: clone um bot que já funciona
Este guia usa o bot open-source do repositório GitHub da Whapi.Cloud. Já cobre envio e recebimento, mídia, contatos, produtos e grupos. O restante do artigo mostra como colocá-lo no ar.
O script deste chatbot inclui funções básicas frequentemente utilizadas por pequenas e médias empresas e abrange a maioria das tarefas:
- Envio de uma mensagem comum;
- Envio de mídia: imagem / arquivo / vídeo;
- Envio de contato (cartão de visita vCard);
- Envio de produto;
- Criação de grupos no WhatsApp;
- Envio de convite para o grupo;
- Envio de mensagem em grupo no WhatsApp;
- Recebimento e processamento de mensagens recebidas;
- Resposta a um comando desconhecido (para implementação de menu, instruções ou mensagem de boas-vindas).
git clone https://github.com/Whapi-Cloud/nodejs-whatsapp-chatbot
Depois de clonar, entre na pasta do projeto:
cd nodejs-whatsapp-chatbot
Instale os pacotes listados no
package.json:
npm install
Isso baixa as dependências que o chatbot precisa para rodar.
Estrutura do projeto
- /files — mídia de exemplo que o bot pode enviar (imagem, PDF, vídeo, vCard). Troque quando quiser.
- config.js —
token,botUrl,porte IDs opcionais degroup/product. - index.js — registra o webhook, escuta em
/hook/messagese mapeia os números 1–9 para ações.
Conecte seu número de WhatsApp
A Whapi.Cloud é um gateway HTTP para WhatsApp, independente da Meta. Você usa qualquer número que já tenha, escaneia um QR no painel e recebe um token Bearer. Sem verificação Meta Business e sem limites de modelo ou janela de mensagem da Cloud API.
Para o bot funcionar não é preciso o celular ficar online. Vincule o número uma vez no painel e rode o bot em qualquer servidor. Se precisar de ajuda, use o chat de suporte do site.
Escaneie o QR code na sua conta
Cadastro. O primeiro passo é se registrar no site da Whapi.Cloud e criar uma conta. É grátis e não pede cartão.
Depois do cadastro você já tem um canal de teste com cota reduzida. Espere ele iniciar (em geral um minuto). Será preciso vincular o celular: é desse número que as mensagens saem. A vantagem é que em poucos minutos você já está no ar.
Para vincular o celular, use o QR ao clicar no canal de teste da sua conta. No WhatsApp do aparelho: Configurações -> Aparelhos conectados -> Conectar um aparelho -> Escanear código QR.
Você pode pular as telas de nome do canal e webhook no assistente — o bot configura o webhook na inicialização.
Agora você tem o token da API, necessário para testar e chamar os endpoints. Guarde-o, vai usar mais de uma vez. No card do canal, copie o token e cole no
config.js como token. As chamadas a https://gate.whapi.cloud usam Bearer.
Antes de iniciar o bot
- Token do canal colado no
config.js. - Um segundo celular para testar: o bot ignora mensagens do número conectado.
- URL HTTPS pública. No local use ngrok; em produção, qualquer host com HTTPS.
Dê ao bot uma URL HTTPS pública
Um webhook é o aviso que a Whapi.Cloud manda ao seu bot sempre que algo acontece na conta WhatsApp conectada: um texto novo, mudança de status, convite de grupo.
Em vez de perguntar «tem mensagem nova?» o tempo todo, seu script recebe um POST com o evento assim que ele acontece.
Exemplo: o contato A manda «oi» -> a Whapi.Cloud faz POST de um JSON em
/hook/messages no seu servidor -> o bot lê o comando e responde. Você não cola a URL no painel; o bot registra a partir do config.js na subida.A Whapi.Cloud entrega mensagens recebidas com um POST na sua URL HTTPS pública. Você não cola essa URL no painel. Coloque em
config.js como botUrl; na subida o repositório registra pela API de configurações do canal.Túnel local com ngrok
A
port padrão no config.js é 80 (não use 443). Baixe o ngrok e rode ngrok http 80 — ou a porta que você definiu no config.js.Copie a URL de encaminhamento
https://. Defina botUrl como esse host mais /hook, por exemplo botUrl: "https://84c7-151-33-282-113.ngrok-free.app/hook".
Mantenha o sufixo
/hook. O servidor escuta POST em /hook/messages; botUrl é o prefixo gravado nas configurações do canal.Ao rodar
node index.js, o bot envia PATCH /settings com essa URL e o evento messages. As mensagens do WhatsApp chegam no seu processo. Você pode ignorar os campos de webhook no painel, a menos que queira ver o que foi registrado.O que a produção precisa
O host precisa ser alcançável na internet via HTTPS, e o processo Node tem que continuar rodando para aceitar POST. Se mudar o
botUrl, reinicie o bot para registrar o webhook de novo.Iniciar o bot
Confirme
token e botUrl no config.js e, na raiz do projeto, rode node index.js. Você deve ver o log de listening. De um celular diferente, envie qualquer texto para o número conectado. O bot responde com um menu numerado.Menu de comandos
- Mensagem de texto simples
- Enviar imagem
- Enviar documento
- Enviar vídeo
- Enviar contato
- Enviar produto
- Criar grupo
- Texto simples para o grupo
- Obter os ids dos seus três grupos
Envie só o número, por exemplo 1. Qualquer outra coisa devolve esta lista.
Os comandos 6 e 8 usam
product e group no config.js. Pule-os no primeiro teste. Quando precisar, liste IDs com GET /groups e GET /business/products.Solução de problemas
O bot não responde
Escreva de outro celular — o script ignora
from_me. Confira o token, se botUrl termina em /hook, se o ngrok (ou o host) ainda está no ar e se o processo imprimiu a mensagem de listening.O bot envia mensagens em loop
Mantenha
if (message.from_me) continue. Sem isso o bot responde às próprias mensagens e não para.Funciona em alguns chats e em outros não
O Sandbox limita conversas ativas (hoje 5 por mês). Um sexto chat não recebe resposta até você subir de plano ou o limite resetar.
Enviar mensagens de WhatsApp pelo Node.js
O bot clonado já envia, recebe, mídia, contatos, produtos, grupos e mais. Os trechos abaixo são o mesmo padrão HTTP interno: um
fetch para https://gate.whapi.cloud com o Bearer.Enviar uma mensagem de texto
Envie um texto simples para um chat ou grupo:
const response = await fetch('https://gate.whapi.cloud/messages/text', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
body: 'Hello from the cloned bot'
})
});
const data = await response.json();
console.log(data);
Enviar um documento
Envie um documento com URL pública ou payload em base64:
const response = await fetch('https://gate.whapi.cloud/messages/document', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '[email protected]',
media: 'https://example.com/file.pdf',
caption: 'Document from the bot'
})
});
const data = await response.json();
console.log(data);
A lista completa de tipos e payloads está na referência da API.
Trabalhar com grupos do WhatsApp
O bot lista os grupos dos quais você participa e reage a mensagens de grupo. Estes exemplos reutilizam o mesmo Bearer e o endpoint
/groups.Listar seus grupos
Busque os grupos visíveis para o número conectado:
const response = await fetch('https://gate.whapi.cloud/groups', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
const { groups } = await response.json();
console.log(groups);
Cada objeto de grupo inclui nome, foto, descrição e um array de participantes.
Contar participantes do grupo
Percorra o array para imprimir o nome de cada grupo e a quantidade de membros:
groups.forEach(group => {
console.log(`Group Name: ${group.name}`);
console.log(`Participants: ${group.participants.length}`);
});
Lidar com mensagens de grupo
IDs de chat de grupo terminam em
@g.us. Webhooks recebidos usam o mesmo sufixo; o bot clonado já ramifica nisso quando um comando mira um grupo.
// Do bot clonado: mensagens de grupo usam chat_id terminando em @g.us
const messages = req.body.messages;
messages.forEach(message => {
if (message.chat_id.endsWith('@g.us')) {
console.log(`Group message: ${message.text?.body}`);
}
});
Para criar grupos, convidar ou gerenciar admins, veja o guia de grupos na documentação.
O comando 7 cria um grupo com o remetente como participante. O 8 manda texto para
config.group. Defina esse ID antes de usar esses números.Mantenha online
Deixe
node index.js rodando numa máquina com URL HTTPS pública e defina botUrl como https://seu-host/hook. Este bot é um processo Express de longa duração, não uma função serverless de um disparo — um VPS ou qualquer host Node com HTTPS basta. Reinicie se mudar o botUrl para registrar o webhook de novo.Para que seu chatbot do WhatsApp esteja disponível 24/7, é necessário hospedá-lo em uma plataforma de hospedagem confiável. Você pode usar seu próprio servidor, mas neste capítulo vamos considerar as três plataformas mais populares — Firebase, AWS e Heroku — e passar pelos passos básicos para implantar seu bot em cada uma delas.
A escolha da plataforma depende das suas preferências, orçamento e requisitos do projeto. Cada uma das plataformas consideradas oferece suas próprias oportunidades e vantagens únicas. Firebase e AWS Lambda fornecem um backend poderoso sem a necessidade de gerenciar um servidor, enquanto o Heroku oferece a simplicidade de implantação de aplicativos baseados em Git.
Firebase
O Firebase oferece a funcionalidade Cloud Functions, que permite executar seu bot sem se preocupar com a infraestrutura do servidor. Na nossa opinião, esta é a opção mais otimizada.
- 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)
A AWS Lambda permite executar código em resposta a gatilhos de outros serviços AWS, o que o torna uma boa escolha para um bot.
- 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
O Heroku oferece uma plataforma simples para hospedagem de aplicativos, capaz de implantar automaticamente o código do seu repositório Git.
- 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.
Próximos passos
Com o bot no ar você constrói em cima. Envie arquivos por URL pública; distribua leads em grupos do WhatsApp; conecte um CRM para reservas e pedidos atualizarem em tempo real; use enquetes no lugar de botões; publique status e reaja às mensagens; ou valide números antes de um disparo. Veja a documentação ou explore grupos, canais, comunidades, MCP, n8n, Make, agent skills e o hub de chatbots.
status · verificador de números · docs da API · agent skills
