Receber mensagens do WhatsApp por webhook

Objetivo

Ao final, o seu sistema vai receber, por webhook, cada mensagem que chegar ao número conectado. Você sobe um servidor Node.js, aponta a API para ele e vê a mensagem aparecer no terminal.

Pré-requisitos

• Uma instância conectada (Conexão).
• O ID e o token da instância.
• Node.js 18 ou mais novo.
• Uma forma de dar ao seu computador um endereço HTTPS público, como um túnel. A API recusa localhost e endereços da rede interna com 400 e url_not_allowed.

1. Crie o servidor

Salve como receber.mjs:

import { createServer } from 'node:http'

const PORTA = 3000
// Em produção, guarde isso num banco ou no Redis. Aqui basta a memória.
const entregasProcessadas = new Set()

function tratar(evento, corpo) {
  if (evento === 'message.received') {
    const { from, type, text } = corpo.data
    console.log(`Mensagem de ${from} (${type}): ${text ?? '[sem texto]'}`)
  } else {
    console.log(`Evento recebido: ${evento}`)
  }
}

createServer((req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhook') {
    res.writeHead(404).end()
    return
  }
  const pedacos = []
  req.on('data', (pedaco) => pedacos.push(pedaco))
  req.on('end', () => {
    // Confirme primeiro, trabalhe depois.
    res.writeHead(200).end('ok')

    const entrega = req.headers['x-nigora-delivery']
    if (entregasProcessadas.has(entrega)) return
    try {
      tratar(req.headers['x-nigora-event'], JSON.parse(Buffer.concat(pedacos).toString('utf8')))
      entregasProcessadas.add(entrega)
    } catch {
      console.error('Corpo ilegível, ignorado.')
    }
  })
}).listen(PORTA, () => console.log(`Ouvindo na porta ${PORTA}, rota /webhook`))

O servidor responde 200 antes de processar. A API espera uma resposta 2xx em até 10 segundos. Se ela não vier, a entrega conta como falha e é repetida. Por isso o código também guarda o x-nigora-delivery: se a mesma entrega chegar de novo, ela é ignorada.

2. Execute e abra o túnel

node receber.mjs

Saída esperada:

Ouvindo na porta 3000, rota /webhook

Em outro terminal, abra um túnel para a porta 3000. Ele devolve um endereço HTTPS público. Use esse endereço, com /webhook no final, no próximo passo.

3. Aponte a API para o servidor

PUT /v1/instances/{instanceId}/webhooks substitui toda a configuração. Por isso envie o conjunto completo:

curl -X PUT https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": {
      "message.received": { "url": "https://SEU_ENDERECO_PUBLICO/webhook", "enabled": true }
    },
    "notifySentByMe": false,
    "receiveFilters": { "ignoreGroups": true }
  }'

A resposta é 200 e traz a configuração salva, com o secret. Você vai usar o secret no tutorial de validação da assinatura.

4. Teste

Com outro celular, envie uma mensagem para o número conectado. No terminal do servidor aparece algo como:

Mensagem de 5511999999999@s.whatsapp.net (text): Olá!

Não apareceu? Veja o histórico com GET /v1/instances/{instanceId}/webhooks/deliveries. Cada entrega mostra a situação e a última resposta do seu servidor. Para repetir uma entrega, use POST /v1/instances/{instanceId}/webhooks/deliveries/{id}/resend.

Cuidado

Este servidor ainda aceita chamadas de qualquer origem. Antes de ir para produção, confira a assinatura de cada chamada, como mostra o próximo tutorial.

Próximos passos

• Validar a assinatura do webhook: garanta que a chamada veio da API.
• Webhooks: todos os eventos, filtros, tentativas e reenvio.
• Enviando mensagens: responda a quem escreveu.