Como enviar mensagens de WhatsApp com Node.js usando a APIBrasil

O WhatsApp é o canal de comunicação preferido dos brasileiros, e integrá-lo ao seu sistema abre muitas possibilidades: confirmação de pedidos, lembretes de agendamento, envio de boletos e notas fiscais, atendimento automatizado e notificações em tempo real. Neste tutorial você vai aprender a enviar mensagens de WhatsApp com Node.js usando a SDK oficial da APIBrasil.

Vamos percorrer o fluxo completo: conectar um número pelo QR Code, enviar textos e arquivos, receber mensagens por webhook e aplicar as boas práticas que reduzem o risco de bloqueio do número. Os códigos foram validados enquanto escrevíamos este guia, e os prints mostram cada etapa.

Como funciona a API de WhatsApp da APIBrasil

A API de WhatsApp é um serviço do tipo device-based. Cada device representa uma sessão de WhatsApp, ou seja, um número conectado. O fluxo é:

1. Device: você cria um device da API de WhatsApp no painel (ou via API, com a SecretKey) e recebe um DeviceToken.
2. Sessão: com o DeviceToken, inicia a sessão (start) e, opcionalmente, registra webhooks.
3. QR Code: busca o QR Code (qrcode) e escaneia com o celular, como faria no WhatsApp Web.
4. Envios: a partir daí, o seu código envia mensagens pelo número conectado (sendText, sendFile, sendAudio, sendLocation e dezenas de outras ações).
5. Recebimento: as mensagens que chegam ao número são entregues ao seu webhook.

Todas as requisições levam dois cabeçalhos: o Bearer token (sua conta) e o DeviceToken (a sessão). Quer ter um número para vendas e outro para suporte? Basta criar dois devices.

Pré-requisitos

• Node.js 20.6+ instalado (nodejs.org).
• Uma conta na APIBrasil com a API de WhatsApp ativa, o Bearer token e o DeviceToken do device de WhatsApp.
• Um celular com o WhatsApp do número que será conectado. Prefira um número dedicado à aplicação, e não o seu pessoal.
• Noções de JavaScript assíncrono (async/await). Se precisar de uma base, veja Minha primeira API em Node.js com Express.

Passo 1: criando o projeto

mkdir whatsapp-node && cd whatsapp-node
npm init -y
npm pkg set type=module
npm install apigratis-sdk-nodejs express

Crie o arquivo .env com as credenciais e a URL pública do seu webhook (vamos criá-lo no passo 5):

APIBRASIL_BEARER_TOKEN=seu_bearer_token
APIBRASIL_DEVICE_TOKEN=device_token_do_whatsapp
WEBHOOK_URL=https://seu-dominio.com.br/webhook/whatsapp

Lembre-se de adicionar o .env ao .gitignore. Um DeviceToken exposto permite que outra pessoa envie mensagens pelo seu número. Entenda os cuidados em Variáveis de ambiente e arquivo .env.

Passo 2: iniciando a sessão e obtendo o QR Code

Crie o conectar.js:

O que acontece aqui:

• api.whatsapp.start() inicia a sessão. É nesta chamada que os webhooks são registrados: webhook_wh_message recebe as mensagens, e existem também webhook_wh_status, webhook_wh_connect e webhook_wh_qrcode para eventos de status, conexão e novo QR Code.
• api.whatsapp.qrcode() retorna o QR Code como data URI em base64 (data:image/png;base64,...). Numa aplicação web, você o colocaria direto em um <img src>; aqui, gravamos em qrcode.png.
• Se a sessão já estiver conectada, não há QR Code para mostrar — o script avisa isso.
• Um PermissionError (HTTP 403) quase sempre significa que o DeviceToken é de outra API ou que o IP não está na whitelist da conta.

Execute:

node --env-file=.env conectar.js

Abra o qrcode.png e escaneie com o celular:

O QR Code expira em poucos segundos. Se não der tempo, rode o script de novo. Depois de conectado, a sessão permanece ativa e você não precisa repetir esse passo a cada envio.

Passo 3: enviando mensagens de WhatsApp com Node.js

Agora a parte principal. Crie o enviar.js:

Destaques do código:

• Validação do número: exigimos o formato 55 + DDD + número (10 ou 11 dígitos após o 55). Validar antes de chamar a API evita erros e requisições desperdiçadas.
• sendText envia texto. O parâmetro opcional time_typing mostra “digitando…” para o destinatário por alguns milissegundos antes da entrega, deixando a interação mais natural.
• sendFile envia um arquivo a partir de uma URL pública, com legenda (caption). Para arquivos locais, existe o sendFile64, que recebe o conteúdo em base64.
• Erros tipados: RateLimitError indica que o limite de requisições foi atingido e traz o tempo de espera sugerido em retryAfterMs; qualquer outro erro da API é um ApiBrasilError com status e message.

Rode passando o número de destino:

node --env-file=.env enviar.js 5511999999999

Outros tipos de mensagem

A SDK tem métodos para os tipos mais comuns e aceita qualquer ação da documentação via request:

// Áudio (por URL)
await api.whatsapp.sendAudio({ number, path: 'https://exemplo.com/audio.mp3' });

// Localização
await api.whatsapp.sendLocation({ number, lat: -23.5613, lng: -46.6565 });

// Qualquer ação da documentação, mesmo sem método dedicado
await api.whatsapp.request('sendLink', { number, url: 'https://apibrasil.io', text: 'Conheça' });

// Envio assíncrono pela fila do gateway
await api.whatsapp.queue('sendText', { number, text: 'Mensagem processada pela fila 🚀' });

Confira a lista completa de ações e os campos de cada uma em doc.apibrasil.io.

Passo 4: vários números com múltiplos devices

Se a sua aplicação usa mais de um número, crie um cliente por device com withDevice:

const vendas = api.withDevice(process.env.DEVICE_TOKEN_VENDAS);
const suporte = api.withDevice(process.env.DEVICE_TOKEN_SUPORTE);

await vendas.whatsapp.sendText({ number, text: 'Sua proposta foi enviada!' });
await suporte.whatsapp.sendText({ number, text: 'Como podemos ajudar?' });

Passo 5: recebendo mensagens com webhook

Enviar é metade da história. Para responder clientes, criar um chatbot ou registrar conversas, você precisa receber mensagens. Em vez de perguntar à API de tempos em tempos se chegou algo (polling), a APIBrasil avisa o seu sistema fazendo uma requisição POST para a URL que você registrou no start: o webhook.

Um receptor mínimo com Express:

import express from 'express';

const app = express();
app.use(express.json({ limit: '5mb' }));

// A APIBrasil chama esta rota a cada mensagem recebida no número conectado
app.post('/webhook/whatsapp', (req, res) => {
  const evento = req.body;
  console.log('📩 Evento recebido:', JSON.stringify(evento).slice(0, 300));

  // Responda rápido: processe o evento em segundo plano (fila, job etc.)
  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook ouvindo em http://localhost:3000/webhook/whatsapp'));

Antes de conectar à APIBrasil, teste localmente simulando uma chamada com cURL (o corpo abaixo é só um exemplo de teste):

Regras de ouro para webhooks:

• Responda rápido (status 200 em poucos segundos) e processe o conteúdo depois, em uma fila. Se o seu webhook demorar ou falhar, os eventos podem ser reenviados ou perdidos.
• Use HTTPS e uma URL pública. Em desenvolvimento, ferramentas de túnel como ngrok ou Cloudflare Tunnel expõem o seu localhost temporariamente.
• Proteja a rota: use um caminho difícil de adivinhar ou um parâmetro secreto na URL, e valide o formato do corpo recebido.
• Seja idempotente: o mesmo evento pode chegar mais de uma vez. Guarde o identificador da mensagem e ignore repetidos.
• Inspecione o payload real registrando alguns eventos antes de escrever a lógica, e consulte a documentação para os campos de cada tipo de evento.

Boas práticas para não ter o número bloqueado

O WhatsApp combate ativamente spam e comportamento automatizado abusivo. Siga estas práticas:

• Envie apenas para quem autorizou (opt-in) e ofereça forma de parar de receber. Além de evitar bloqueios, é o que pede a LGPD.
• Aqueça números novos: comece com poucos envios por dia e aumente gradualmente.
• Não dispare em massa em paralelo. Use a fila (queue), espaçe os envios e varie o conteúdo. Mensagens idênticas para centenas de pessoas são um sinal clássico de spam.
• Personalize as mensagens com nome e contexto. Conteúdo relevante gera respostas, e conversas de mão dupla são vistas como uso legítimo.
• Monitore bloqueios e denúncias: se muitos destinatários bloquearem o número, reduza o volume e revise o conteúdo.
• Use um número dedicado à aplicação, nunca o pessoal.

Casos de uso práticos

• E-commerce: confirmação de pedido, código de rastreio, aviso de saída para entrega e pesquisa de satisfação.
• Clínicas e salões: lembrete de consulta com opção de confirmar ou remarcar.
• Financeiro: envio de boleto ou chave Pix e lembrete de vencimento.
• Atendimento: chatbot de primeiro nível que responde dúvidas frequentes e transfere para um humano.
• Sistemas internos: alertas de monitoramento para a equipe de plantão.

Combine com outros serviços da mesma plataforma: valide o endereço com consulta de CEP antes de confirmar a entrega, ou use o SMS com PHP como canal alternativo para quem não tem WhatsApp.

Erros comuns

403 Forbidden — DeviceToken de outra API, device de outra conta ou IP fora da whitelist.

401 Unauthorized — Bearer token ausente ou expirado. Verifique se o script foi executado com --env-file=.env.

A mensagem não chega — confirme que a sessão está conectada (o celular pode ter desconectado o aparelho), que o número está no formato 55DDDNUMERO e que ele tem WhatsApp.

QR Code expirado — rode o conectar.js de novo e escaneie mais rápido, ou registre o webhook_wh_qrcode para receber cada novo QR Code automaticamente.

429 Too Many Requests — você atingiu o limite por minuto. A SDK já refaz a chamada automaticamente respeitando o Retry-After; para volume alto, use a fila.

Perguntas frequentes

Preciso deixar o celular ligado?

Na maioria dos casos, não. O WhatsApp funciona no modo multiaparelho: depois de conectado, a sessão continua ativa mesmo com o celular desligado por um tempo. Se o celular ficar muito tempo sem conexão, o WhatsApp pode desconectar os aparelhos vinculados, e será necessário escanear o QR Code novamente.

Qual a diferença para a API oficial do WhatsApp Business (Cloud API)?

A API oficial da Meta exige aprovação, modelos de mensagem pré-aprovados para iniciar conversas e cobra por conversa. A integração por sessão, como a deste tutorial, conecta um número via QR Code e oferece mais flexibilidade, mas exige atenção redobrada às boas práticas para evitar bloqueios. A escolha depende do volume, do tipo de uso e das exigências do seu negócio.

Posso enviar mensagens para grupos?

Sim. A API tem ações para listar grupos, obter membros e enviar mensagens para grupos, além de gerenciar participantes. Consulte as ações disponíveis na documentação.

A SDK funciona com TypeScript?

Sim. A apigratis-sdk-nodejs já inclui os tipos, com autocomplete das ações do WhatsApp e dos parâmetros. Basta usar import { ApiBrasil } from 'apigratis-sdk-nodejs' em um projeto TypeScript.

E se eu usar PHP em vez de Node.js?

A SDK PHP tem a mesma estrutura: $api->whatsapp->sendText([...]). Veja como instalá-la e tratar erros no tutorial Como enviar SMS com PHP usando a SDK da APIBrasil.

Conclusão

Você aprendeu a enviar mensagens de WhatsApp com Node.js: entendeu o modelo de devices e sessões, conectou um número via QR Code, enviou textos e arquivos com a SDK da APIBrasil, tratou erros tipados, recebeu mensagens por webhook e conheceu as práticas que mantêm o número saudável. Com essa base, você pode construir notificações transacionais, lembretes automáticos e até chatbots completos.

Esta é a última aula da nossa série básica de tutoriais. Se chegou até aqui, recapitule a trilha: Docker para iniciantes, Laravel, primeira API em Node.js, SMS com PHP, Git e GitHub, cURL e Postman, Docker Compose, variáveis de ambiente e consulta de CEP. E, para colocar tudo em produção, crie sua conta na APIBrasil.