Recibir mensajes de WhatsApp por webhook

Objetivo

Al final, su sistema recibirá por webhook cada mensaje que llegue al número conectado. Usted levanta un servidor Node.js, apunta la API hacia él y ve el mensaje aparecer en la terminal.

Requisitos previos

• Una instancia conectada (Conexión).
• El ID y el token de la instancia.
• Node.js 18 o más nuevo.
• Una forma de darle a su computadora una dirección HTTPS pública, como un túnel. La API rechaza localhost y las direcciones de la red interna con 400 y url_not_allowed.

1. Cree el servidor

Guárdelo 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`))

El servidor responde 200 antes de procesar. La API espera una respuesta 2xx en un máximo de 10 segundos. Si no llega, la entrega cuenta como fallida y se repite. Por eso el código también guarda el x-nigora-delivery: si la misma entrega llega de nuevo, se ignora.

2. Ejecute y abra el túnel

node receber.mjs

Salida esperada:

Ouvindo na porta 3000, rota /webhook

En otra terminal, abra un túnel hacia el puerto 3000. Le devuelve una dirección HTTPS pública. Use esa dirección, con /webhook al final, en el próximo paso.

3. Apunte la API hacia el servidor

PUT /v1/instances/{instanceId}/webhooks reemplaza toda la configuración. Por eso envíe siempre el 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 }
  }'

La respuesta es 200 y trae la configuración guardada, con el secret. Usará el secret en el tutorial de validación de la firma.

4. Pruebe

Con otro celular, envíe un mensaje al número conectado. En la terminal del servidor aparece algo como:

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

¿No apareció? Vea el historial con GET /v1/instances/{instanceId}/webhooks/deliveries. Cada entrega muestra la situación y la última respuesta de su servidor. Para repetir una entrega, use POST /v1/instances/{instanceId}/webhooks/deliveries/{id}/resend.

Precaución

Este servidor todavía acepta llamadas de cualquier origen. Antes de pasar a producción, verifique la firma de cada llamada, como muestra el próximo tutorial.

Próximos pasos

• Validar la firma del webhook: garantice que la llamada vino de la API.
• Webhooks: todos los eventos, filtros, reintentos y reenvío.
• Envío de mensajes: responda a quien escribió.