WhatsApp Cloud API: Webhook em Node.js em 15 Min

Você tem uma conta Meta Business, quer receber mensagens do WhatsApp no seu servidor e responder com IA. Parece simples, mas a documentação oficial tem 47 páginas e assume que você já sabe o que é um webhook. Esse tutorial corta o caminho: em 15 minutos você tem um endpoint recebendo mensagens reais.

O Que Você Vai Construir

Um servidor Express.js que recebe mensagens da WhatsApp Cloud API via webhook, processa o conteúdo e responde automaticamente. A base para qualquer chatbot, agente de IA ou automação no WhatsApp.

Pré-requisitos: Node.js 18+, conta Meta Business (pode ser test account), ngrok para desenvolvimento local.

Passo 1: Crie o Projeto

mkdir whatsapp-webhook && cd whatsapp-webhook
npm init -y
npm install express dotenv

Crie um arquivo .env com suas credenciais:

VERIFY_TOKEN=seu_token_secreto_aqui
WHATSAPP_TOKEN=seu_access_token_meta
PHONE_NUMBER_ID=seu_phone_number_id

O VERIFY_TOKEN é uma string que você inventa. O WHATSAPP_TOKEN e PHONE_NUMBER_ID vêm do painel da Meta em developers.facebook.com → sua app → WhatsApp → Getting Started.

Passo 2: Configure o Servidor Express

Crie index.js:

require('dotenv').config();
const express = require('express');
const app = express();
app.use(express.json());

const { VERIFY_TOKEN, WHATSAPP_TOKEN, PHONE_NUMBER_ID } = process.env;

// Verificação do webhook (GET)
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === VERIFY_TOKEN) {
    console.log('Webhook verificado!');
    return res.status(200).send(challenge);
  }
  res.sendStatus(403);
});

// Receber mensagens (POST)
app.post('/webhook', async (req, res) => {
  const body = req.body;

  if (body.object !== 'whatsapp_business_account') {
    return res.sendStatus(404);
  }

  const entry = body.entry?.[0];
  const changes = entry?.changes?.[0];
  const message = changes?.value?.messages?.[0];

  if (!message) return res.sendStatus(200);

  const from = message.from; // número do remetente
  const text = message.text?.body; // texto da mensagem

  console.log(`Mensagem de ${from}: ${text}`);

  // Responder
  await sendMessage(from, `Recebi: "${text}". Em breve respondo com IA!`);

  res.sendStatus(200);
});

async function sendMessage(to, text) {
  const url = `https://graph.facebook.com/v21.0/${PHONE_NUMBER_ID}/messages`;

  await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${WHATSAPP_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to,
      type: 'text',
      text: { body: text },
    }),
  });
}

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

Passo 3: Exponha Com ngrok

Para desenvolvimento local, o webhook precisa de HTTPS público. O ngrok resolve:

node index.js &
ngrok http 3000

O ngrok gera uma URL tipo https://abc123.ngrok.io. Copie essa URL.

Passo 4: Registre o Webhook na Meta

1. Vá em developers.facebook.com → sua app → WhatsApp → Configuration

2. Em "Webhook", clique "Edit"

3. Cole a URL: https://abc123.ngrok.io/webhook

4. Cole o VERIFY_TOKEN que você definiu no .env

5. Clique "Verify and Save"

6. Em "Webhook fields", marque messages

Dado-chave: Se a verificação falhar, cheque se o ngrok está rodando e se o VERIFY_TOKEN no .env bate com o que você colocou na Meta. 90% dos erros de webhook são token errado ou servidor offline.

Passo 5: Teste

Mande uma mensagem para o número de teste do WhatsApp (aparece no painel da Meta). Você deve ver no console:

Mensagem de 5511999999999: Olá!

E receber de volta: "Recebi: 'Olá!'. Em breve respondo com IA!"

Próximo Passo: Adicionar IA

Com o webhook funcionando, adicionar IA é trocar a resposta fixa por uma chamada à API da OpenAI ou Claude:

npm install openai

No handler do POST, substitua o sendMessage fixo por:

const OpenAI = require('openai');
const openai = new OpenAI({ apiKey: process.env.OPENAI_KEY });

// Dentro do handler POST:
const completion = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'system', content: 'Você é um assistente prestativo.' },
    { role: 'user', content: text }
  ],
});

const reply = completion.choices[0].message.content;
await sendMessage(from, reply);

Em 5 linhas extras, seu bot já responde com IA. O custo do gpt-4o-mini é centavos por conversa.

Para Produção: O Que Muda

• Trocar ngrok por domínio real: Deploy no Railway, Render, Cloud Run ou VPS com HTTPS

• Token permanente: O token do painel é temporário (24h). Gere um System User Token para produção

• Fila de mensagens: Para volume alto, use Redis/BullMQ entre webhook e processamento

• Memória: Salve conversas em banco para contexto entre mensagens

Se você quer pular toda essa infra e ir direto para agentes de IA no WhatsApp com API pronta, webhooks configurados e deploy em minutos, a Verboo entrega isso pronto. Veja como funciona