Recibir los mensajes de WhatsApp en tu sistema

1. Armá el receptorCopiar el enlace a esta sección

Tu receptor tiene que hacer cuatro cosas, en este orden:

1. Leer el cuerpo crudo, tal como llegó, sin parsearlo.
2. Verificar la firma de la cabecera X-Funnelchat-Signature con el secreto de la suscripción. Si no es válida, responder 400 y no hacer nada. La fórmula y el código probado en Node.js, Python y PHP están en Verificar la firma: copiá el de tu lenguaje a tu proyecto tal cual (los ejemplos de abajo lo importan como verificar-firma.js y verificar_firma.py).
3. Responder 2xx enseguida. Si no respondés, la entrega cuenta como fallida y se reintenta. Procesá el mensaje después, en segundo plano.
4. Descartar los repetidos por id. La entrega es «al menos una vez»: el mismo evento puede llegar más de una vez, siempre con el mismo id en el cuerpo.

Leé type e id del cuerpo ya verificado, no de las cabeceras: solo el cuerpo está firmado.

// receptor.js · Node 18+ con Express
const express = require('express');
const { verificarFirma } = require('./verificar-firma'); // el código de /docs/webhooks/#firma

const app = express();
const procesados = new Set(); // en producción, guardá los id en tu base de datos

app.post('/hooks/funnelchat', express.raw({ type: 'application/json' }), (req, res) => {
  const firma = req.get('X-Funnelchat-Signature');
  if (!verificarFirma(req.body, firma, process.env.FUNNELCHAT_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }

  const evento = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200); // primero respondé; después procesá

  if (procesados.has(evento.id)) return; // repetido: ya lo procesaste
  if (evento.type !== 'message.received') return; // por ejemplo, webhook.test

  setImmediate(async () => {
    await guardarMensaje(evento.data); // en producción, mandalo a una cola
    procesados.add(evento.id);
  });
});

async function guardarMensaje({ message, contact, receiver, device_id }) {
  console.log(`${contact.phone} le escribió a ${receiver.phone} (número ${device_id}): [${message.type}] ${message.text ?? ''}`);
}

app.listen(3000);

FUNNELCHAT_WEBHOOK_SECRET es el secreto de la suscripción que vas a crear en el paso siguiente. Hasta tenerlo, tu receptor rechaza todo con 400, y está bien.

2. Suscribite a message.receivedCopiar el enlace a esta sección

Con el receptor publicado, creá la suscripción. Hay un solo lugar para suscribirse a los eventos de las tres áreas, /api/v1/webhooks. Pide webhooks:write y, por ser un evento de conversations, conversations:read.

curl -X POST "https://api.funnelchat.com/api/v1/webhooks" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.example/hooks/funnelchat",
    "description": "Mensajes entrantes",
    "events": ["message.received"]
  }'

La respuesta (201) es la suscripción, sin envoltorio data. Estos son sus campos según la especificación; los valores son de ejemplo:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "url": "https://tu-servidor.example/hooks/funnelchat",
  "description": "Mensajes entrantes",
  "events": ["message.received"],
  "filters": {},
  "status": "active",
  "disabled_reason": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "secret_rotated_at": null,
  "created_at": "2026-10-01T12:00:00+00:00",
  "updated_at": "2026-10-01T12:00:00+00:00",
  "migration": null,
  "secret": "whsec_<secreto de firma>",
  "secret_notice": "Guardá este secreto ahora: es la única vez que se muestra. Con él validás la firma del header de cada entrega."
}

3. Probá la entregaCopiar el enlace a esta sección

No hace falta esperar a que alguien escriba: Enviar un evento de prueba manda ya un evento webhook.test a tu URL, firmado igual que uno real, y te dice cómo le fue. {id} es el id del paso anterior (en el ejemplo de curl, la variable WEBHOOK_ID). Pide webhooks:write.

curl -X POST "https://api.funnelchat.com/api/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $FC_API_KEY" \
  -H "Accept: application/json"

Respuesta de ejemplo (200, con los campos de la especificación):

{
  "succeeded": true,
  "response_status": 200,
  "error": null,
  "duration_ms": 184,
  "delivery_id": 9012
}

La prueba llegó si succeeded es true. Si no, response_status y error dicen por qué (non_2xx, timeout, connection_failed, tls_error, destination_not_allowed…); el intento queda además en Listar entregas de un webhook, junto con todas las entregas reales. La prueba no se reintenta.

4. Leé el mensajeCopiar el enlace a esta sección

Cuando un contacto le escribe a uno de tus números, llega esto (ejemplo del catálogo de eventos):

{
  "id": "evt_000000000000000000000001",
  "type": "message.received",
  "version": 1,
  "occurred_at": "2026-10-01T12:00:00Z",
  "data": {
    "message": {
      "id": 1001,
      "type": "text",
      "text": "Hola, quiero más información",
      "media": null
    },
    "contact": {
      "id": 2001,
      "name": "Contacto de ejemplo",
      "phone": "+5491100000000"
    },
    "receiver": {
      "phone": "+5491100000001"
    },
    "device_id": 4521
  }
}

• Los teléfonos vienen con + y el código de país. La API de contactos los guarda sin +: para buscar al contacto, quitáselo antes (El teléfono en los eventos y en la API).
• Tolerá campos y valores nuevos. El catálogo anuncia datos planificados dentro de este evento que el ejemplo de hoy todavía no trae. Si llega algo que no conocés, respondé 2xx igual.
• Para saber a cuál de tus números le escribieron, usá device_id: es el id de Listar números (pide accounts:read).