API do WhatsApp Business com Node.js: Tutorial Completo 2026

Node.js é a escolha mais popular para integrar com a API do WhatsApp Business por ser a linguagem da web e ter excelente suporte ao modelo assíncrono exigido pelos webhooks. Este tutorial cobre todos os casos de uso da API com exemplos de código prontos para adaptar ao seu projeto.

Configuração inicial do projeto

O projeto precisa de duas dependências principais: axios para as chamadas HTTP à Graph API da Meta e express para servir o webhook. Adicione dotenv para gerenciar as variáveis de ambiente com segurança.

1. mkdir whatsapp-api && cd whatsapp-api && npm init -y
2. npm install express axios dotenv
3. Crie .env com: WHATSAPP_TOKEN, PHONE_NUMBER_ID, VERIFY_TOKEN, APP_SECRET, PORT
4. Crie src/whatsapp.js com as funções de envio e src/webhook.js com o servidor Express
5. Adicione nodemon como dependência de desenvolvimento para hot reload

Módulo de envio: funções para cada tipo de mensagem

Organize as funções de envio em um módulo separado para reutilização. Cada função recebe o número do destinatário e os dados específicos do tipo de mensagem.

• sendTextMessage(to, text): envia mensagem de texto simples
• sendTemplateMessage(to, templateName, languageCode, components): envia template aprovado
• sendImageMessage(to, imageUrl, caption): envia imagem com legenda opcional
• sendDocumentMessage(to, docUrl, filename, caption): envia PDF ou documento
• sendButtonMessage(to, text, buttons): envia mensagem com até 3 botões de resposta rápida
• sendListMessage(to, header, body, sections): envia menu de lista interativa
• markAsRead(messageId): marca mensagem como lida (remove indicador de pendente)

Processando o payload do webhook

O payload da Meta tem uma estrutura aninhada. A forma mais segura de navegar nele é com optional chaining para evitar erros quando campos opcionais não existem.

Extraia o objeto de mensagem com: const message = req.body?.entry?.[0]?.changes?.[0]?.value?.messages?.[0]. Verifique se message existe antes de processar.

Gerenciamento de sessão e contexto de conversa

Para bots com múltiplos passos, você precisa de gerenciamento de estado por usuário. Em desenvolvimento, um Map em memória funciona. Em produção, use Redis para persistência e compartilhamento entre instâncias.

• Guarde o estado por número de telefone: sessions.set(phoneNumber, { step, data })
• Implemente timeout de sessão: limpe sessões inativas após 30 minutos
• Redis com ioredis: perfeito para produção com múltiplos workers
• Separe o estado de sessão do histórico de conversa para chatbots com IA

Testando a integração localmente

Para testar sem fazer deploy, use o ngrok para expor seu servidor local. Registre o URL do ngrok no Meta Business Manager como webhook temporário e envie mensagens do seu próprio WhatsApp para o número da API.

1. npm install -g ngrok && ngrok http 3000
2. Copie o URL HTTPS gerado pelo ngrok
3. No Meta Business Manager, acesse Configurações do App > Webhooks
4. Cole o URL + /webhook no campo Callback URL e seu VERIFY_TOKEN no campo Token
5. Clique em Verificar e salvar
6. Assine os campos messages e message_deliveries
7. Envie uma mensagem de teste e veja o log no terminal

Boas práticas para produção

Antes de ir para produção, implemente validação de assinatura dos webhooks, rate limiting, retry com backoff exponencial para falhas de envio e logging estruturado.

• Valide X-Hub-Signature-256 em toda requisição do webhook
• Use uma fila (BullMQ + Redis) para processar mensagens assincronamente
• Configure alertas para webhooks com taxa de erro acima de 1%
• Implemente circuit breaker para chamadas à API da Meta
• Guarde logs de todas as mensagens enviadas e recebidas por 90 dias

Perguntas frequentes