Recibir mensajes reales

1.El objetivo: que Meta te hable a ti

Hasta ahora, los mensajes de WhatsApp que tu código procesó eran archivos JSON de ejemplo (test/payloads/*.json). En esta lección ocurre el cambio importante: escribes desde tu celular y el mensaje llega a tu servidor. Para eso hay que hacer tres cosas:

1. Que tu servidor sea alcanzable desde internet por HTTPS.
2. Registrar esa dirección en Meta y superar la verificación.
3. Suscribirte a los eventos que quieres recibir.

Requisito: haber hecho la lección 12 (app, número de prueba, destinatario, APP_SECRET, WA_PHONE_ID y un token) y tener el Worker de las lecciones 10 y 11.

2.Qué exige Meta de tu endpoint

La documentación oficial de webhooks establece estas condiciones:

• La URL debe responder por HTTPS con un certificado válido. Los certificados autofirmados no se aceptan. Por eso http://localhost:8787 no sirve tal cual.
• Registras la URL junto con un token de verificación (Verify Token): un texto cualquiera que tú inventas.
• Cada notificación llega por POST y debes responder 200 OK.
• Cada POST trae la cabecera X-Hub-Signature-256, con sha256= seguido de la firma calculada con tu App Secret. Validarla es opcional según la documentación, pero recomendada; el Worker del curso la exige.
• Si no respondes bien, Meta reintenta de inmediato y luego varias veces durante 36 horas, cada vez con menos frecuencia. Las notificaciones pueden llegar duplicadas o en lote, así que hay que procesar cada una por separado y deduplicar.

Dos ideas de diseño del Worker de referencia salen directamente de esa lista: la idempotencia (la clave visto:<wamid> que evita responder dos veces al mismo mensaje) y responder 200 al instante y trabajar en segundo plano con ctx.waitUntil.

3.El apretón de manos de verificación

Cuando pulsas «Verificar y guardar» en el panel, Meta envía un GET a tu URL con tres parámetros:

Tu código debe comprobar que el token coincide y responder 200 con el texto de hub.challenge en el cuerpo. Si no, responder un error. Esto es lo que hace verificarWebhook en src/worker.js:

function verificarWebhook(url, env) {
  const modo = url.searchParams.get('hub.mode');
  const token = url.searchParams.get('hub.verify_token');
  const reto = url.searchParams.get('hub.challenge');
  if (modo === 'subscribe' && env.VERIFY_TOKEN && token === env.VERIFY_TOKEN && reto) {
    return new Response(reto, { status: 200 });
  }
  return new Response('Prohibido', { status: 403 });
}

Observa los detalles: se exige que env.VERIFY_TOKEN exista (si lo olvidaste configurar, nadie puede verificar contra un valor vacío) y se devuelve solo el reto, sin comillas ni JSON.

Puedes simular a Meta antes de tocar el panel. Estas son las respuestas reales que dio el Worker en una ejecución con un VERIFY_TOKEN de prueba:

GET /webhook?hub.mode=subscribe&hub.verify_token=token-de-prueba&hub.challenge=1158201444
200 1158201444

GET /webhook?hub.mode=subscribe&hub.verify_token=otro&hub.challenge=1
403 Prohibido

Con curl en tu máquina, cuando el Worker corre en local, sería:

curl "http://localhost:8787/webhook?hub.mode=subscribe&hub.verify_token=TU_VERIFY_TOKEN&hub.challenge=12345"

Si ves 12345, la parte de verificación funciona. Haz esta prueba antes de ir a Meta: así separas los fallos de tu código de los fallos del panel.

4.Opción A: túnel temporal con cloudflared

Para ver mensajes llegando a tu computadora, sin desplegar nada, usa un túnel. Un túnel crea una dirección HTTPS pública que reenvía el tráfico a un puerto local.

1. Instala cloudflared desde la documentación de Cloudflare.
2. En una terminal, arranca el Worker en local (necesita .dev.vars con tus valores de la lección 12):

npx wrangler dev

3. En otra terminal, abre el túnel hacia el puerto del Worker (por defecto 8787):

cloudflared tunnel --url http://localhost:8787

cloudflared imprime una dirección temporal https://algo-aleatorio.trycloudflare.com. Según la documentación de Cloudflare, no hace falta cuenta ni dominio, la dirección cambia cada vez que creas un túnel y deja de funcionar al detener el proceso; es solo para pruebas y desarrollo.

Tu URL de webhook será, por ejemplo, https://algo-aleatorio.trycloudflare.com/webhook. Como cambia en cada sesión, tendrás que actualizarla en Meta cada vez que reinicies el túnel; es la molestia que te empuja a la opción B.

5.Opción B: el Worker desplegado

Si ya desplegaste en la lección 11, tienes una URL estable del tipo https://bot-minimarket.TU-SUBDOMINIO.workers.dev. Es la forma recomendada porque no cambia. Sube los secretos si no lo hiciste:

npx wrangler secret put VERIFY_TOKEN
npx wrangler secret put WA_TOKEN
npx wrangler secret put APP_SECRET
npx wrangler deploy

Prueba que está vivo con curl https://bot-minimarket.TU-SUBDOMINIO.workers.dev/salud; debe responder {"ok":true}. Y para ver los registros en tiempo real mientras llegan mensajes:

npx wrangler tail

6.Registrar el webhook en Meta

En el panel de tu app, sección WhatsApp > Configuration («Configuración») según la guía oficial, busca el bloque Webhook:

1. Pulsa Edit («Editar»).
2. En Callback URL pega tu URL completa, terminando en /webhook.
3. En Verify token pega el mismo texto que pusiste en VERIFY_TOKEN.
4. Pulsa Verify and save («Verificar y guardar»).

Si todo va bien, el panel guarda sin errores. Si no, mira los mensajes de error y la tabla de diagnóstico más abajo.

Guardar la URL no basta: además debes suscribirte a los campos que quieres recibir. Para un bot necesitas el campo messages. En el panel verás una tabla de campos del webhook con un interruptor «Subscribe» («Suscribirse») junto a messages. Actívalo. Sin esa suscripción, la verificación es exitosa pero tu servidor jamás recibe un mensaje (un fallo muy frecuente y confuso).

7.La primera prueba real

Con el Worker corriendo y el webhook suscrito:

1. Mantén abierta la terminal de wrangler dev (o wrangler tail).
2. Desde tu celular, escribe hola al número de prueba (el que aparece en API Setup).
3. Observa la terminal.

Lo esperable es que Meta haga un POST a /webhook con un JSON como el de test/payloads/texto.json (con datos de ejemplo, no reales):

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "102290129340398",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "51999000222", "phone_number_id": "106540352242922" },
        "contacts": [{ "profile": { "name": "Cliente Ejemplo" }, "wa_id": "51999000111" }],
        "messages": [{ "from": "51999000111", "id": "wamid.TEXTO001", "timestamp": "1791360000", "text": { "body": "Quiero 2 leches" }, "type": "text" }]
      },
      "field": "messages"
    }]
  }]
}

Tu Worker comprueba la firma, responde 200 ok y procesa el mensaje en segundo plano. Con una firma correcta y con una incorrecta, las respuestas reales fueron:

POST /webhook (firma válida)   -> 200 ok
POST /webhook (firma falsa)    -> 401 Firma inválida

Y como en esa prueba el token de WhatsApp era falso, al intentar contestar el Worker registró el error que devuelve Meta cuando el token no es válido:

WhatsApp respondió 401: Invalid OAuth access token - Cannot parse access token

Es una buena señal de diagnóstico: significa que el mensaje sí llegó y se procesó, y que el fallo está en el envío (token). Con un token real te contestará el bot; el envío es el tema de la lección 14.

8.Mensajes y estados: dos clases de evento

Tu webhook no solo recibe mensajes de clientes. Cuando el bot envía algo, Meta te avisa del destino de cada mensaje con un evento de estado (sent, delivered, read, failed). Llegan por el mismo campo messages, pero en value.statuses en vez de value.messages. La función parsearWebhook de src/whatsapp.js los separa:

for (const msg of valor.messages ?? []) {
  const evento = parsearMensaje(msg, valor.contacts ?? [], phoneNumberId);
  if (evento) eventos.push(evento);
}
for (const st of valor.statuses ?? []) {
  if (!st?.id) continue;
  eventos.push({ tipo: 'estado', id: st.id, estado: st.status, /* ... */ });
}

Por eso, al probar, verás más eventos de los que esperabas: tu mensaje entrante y, después, los estados del mensaje que respondió el bot. No es un error. También aprenderás a ignorar con elegancia lo que no entiendes: imágenes, audios y otros tipos llegan como no_soportado y el bot responde con un texto amable en lugar de romperse.

9.Cuando no llega nada: diagnóstico

10.Errores frecuentes

• Poner la URL de localhost en el panel. Meta no puede alcanzar tu computadora: necesita una URL pública HTTPS (túnel o despliegue).
• Olvidar el /webhook al final de la URL. El Worker acepta el GET de verificación en /webhook; con la raíz también funciona en el código del curso, pero lo correcto es ser explícito.
• Verificar sin suscribirse a messages. La URL queda «verificada» y aun así no llega nada.
• Parsear el JSON antes de comprobar la firma. La firma se calcula sobre el texto exacto; si lo reformateas, deja de coincidir.
• Tardar en responder. Meta reintenta si no recibe 200; responde primero y trabaja después.
• Pegar el token real en la terminal compartida o en capturas. En las pruebas usa siempre valores como token-de-prueba hasta que sea imprescindible.

11.Apuntes para llevar

• Meta exige una URL HTTPS pública con certificado válido; localhost solo sirve con un túnel.
• La verificación es un GET con hub.mode, hub.verify_token y hub.challenge: devuelves el reto si el token coincide.
• Hay que suscribirse al campo messages; la verificación sola no basta.
• Los mensajes llegan por POST firmado (X-Hub-Signature-256); responde 200 rápido y procesa en segundo plano.
• Meta reintenta durante 36 horas y puede duplicar o agrupar: procesa cada evento por separado y deduplica.
• Los eventos de estado llegan por el mismo webhook que los mensajes.

12.Glosario