Hermes Agent en WhatsApp no conecta: soluciones

El bot nunca responde y los logs están mudos

Conectaste Hermes Agent a WhatsApp, el gateway arranca sin errores y el número al que escribes se queda como una piedra. Ningún evento entrante en los logs, ningún acuse de recibo en el teléfono, ninguna pista clara sobre cuál de las diez piezas móviles está rota. WhatsApp es el canal más frágil del stack de Hermes, y casi todos los casos de conexión silenciosa se reducen a una de cuatro causas.

Tres de las cuatro fallan en silencio por diseño, y por eso el setup parece correcto mientras nada funciona. Este post repasa cada causa, cómo confirmar que es la tuya y la solución exacta. Empieza por la primera - el orden importa, porque esa es la que viene pillando a todo el mundo desde mayo de 2026.

Causa 1: WhatsApp Shortcake rompió tu librería de QR

Si estás corriendo Hermes Agent con Baileys, WAHA o cualquier otra librería que raspe WhatsApp Web, y el QR se niega a emparejarse o vuelve a desconectar el bot enseguida, estás chocando con el rollout de Shortcake para dispositivos vinculados. WhatsApp ahora exige un passkey WebAuthn en el dispositivo vinculado, y un servidor headless no tiene passkey que presentar: navigator.credentials.get() falla y el enlace se rechaza con un 428.

Síntoma: el QR se dibuja, tu móvil lo escanea, y o bien el emparejamiento no termina o la sesión muere en pocos minutos. Las sesiones antiguas que se reconectaban solas empezaron a devolver Stream Errored (conflict) desde mayo de 2026 por lo mismo. Si funcionaba en abril y dejó de hacerlo de un día para otro, esta es tu causa.

La solución tiene dos formas:

Pásate a la Cloud API oficial. Es el camino soportado, no es vulnerable a que Meta rompa una librería de scraping un martes cualquiera, y es lo que asume el resto de este post. Configura Hermes Agent con WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID y WHATSAPP_WEBHOOK_VERIFY_TOKEN en lugar del flujo QR. La guía de despliegue de WhatsApp recorre el baile completo de credenciales de principio a fin.
Quédate en Baileys si no tienes otra opción y fija el commit exacto que aún te funciona (los mantenedores siguen los workarounds del passkey en el issue #2672). Asume que el próximo cambio de Meta vuelve a romperte. No es la elección correcta para nada de lo que dependas de verdad.

El resto del post cubre el camino de la Cloud API.

Causa 2: tu WABA no está suscrita a tu app

Es el fallo más común de la Cloud API y el más silencioso. Pones la URL del webhook en el App Dashboard, el GET de verificación pasa, Meta muestra un tick verde junto al endpoint, y ningún evento de mensaje llega nunca.

Lo que ocurre: fijar la URL del webhook en la app es solo la mitad del cableado. Cada WhatsApp Business Account (WABA) tiene que suscribirse por separado a esa app para que sus mensajes se enruten a tu endpoint. El App Dashboard no muestra esa suscripción en ninguna parte, y la interfaz del webhook te deja terminar el setup sin WABA vinculada. Meta llama a esto el problema de shadow delivery y la solución es una llamada a la API que el asistente de setup no menciona.

Comprueba primero:

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

Si el array data está vacío o no contiene el ID de tu app, este es tu problema.

La solución:

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

La llamada devuelve {"success": true} y el siguiente mensaje entrante llega al webhook de Hermes Agent en segundos. No hace falta reiniciar el gateway. Si más adelante rotas el access token, vuelve a ejecutar esta llamada: la suscripción va atada a la app pero la escritura requiere un token con el permiso whatsapp_business_management.

Causa 3: sigues usando el token temporal de 24 horas

El token que Meta enseña en la pantalla de setup de WhatsApp caduca a las 24 horas exactas. Si lo copiaste al .env de Hermes Agent el martes por la tarde y el bot enmudeció el miércoles por la tarde, esta es la razón.

Síntoma: tu gateway loguea OAuthException o HTTP 401 en el próximo envío saliente tras la caducidad. Las llamadas entrantes del webhook desde Meta pueden seguir llegando (no necesitan tu token), pero cada respuesta que Hermes intenta publicar de vuelta falla, así que el bot recibe tu mensaje, genera una respuesta y la pierde por el camino.

La solución es un token permanente de System User, no un token temporal más largo:

En Meta Business Suite abre Users luego System Users y crea un nuevo System User con rol Admin.
Asigna tu app de WhatsApp y tu WhatsApp Business Account a ese System User con Full control.
Pulsa Generate new token, elige tu app y marca tanto whatsapp_business_messaging (necesario para enviar) como whatsapp_business_management (necesario para la llamada subscribed_apps de la Causa 2).
Pon la expiración en Never. Copia el token, ponlo en WHATSAPP_ACCESS_TOKEN, reinicia el gateway.

Compruébalo antes de irte:

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

Debe devolver el ID y el nombre de tu System User, no un error de OAuth.

Causa 4: estás mandando al Phone Number ID equivocado

La Cloud API de WhatsApp usa tres IDs y todos son fáciles de confundir: el número de teléfono, el Phone Number ID y el WABA ID. Hermes Agent necesita el Phone Number ID, no el número. Si pusiste el número de teléfono en WHATSAPP_PHONE_NUMBER_ID, cada llamada saliente devuelve Object with ID '+34...' does not exist y cada llamada entrante llega sin ruta de respuesta.

Para más lío, el Phone Number ID es un número de 15 o 16 dígitos que se parece bastante a un teléfono. No lo es.

Dónde encontrarlo: en el App Dashboard, abre WhatsApp y luego API Setup. El desplegable From lista tus números registrados. Debajo de cada número, en letra pequeña, hay un campo llamado Phone number ID. Ese es el valor que Hermes Agent necesita.

Verifica que el valor que tienes es real:

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

Un ID válido devuelve display_phone_number, verified_name y quality_rating. Un ID equivocado devuelve un error del Graph API cuyo mensaje nombra el ID que no encontró.

Ya que estás, revisa la variable WHATSAPP_BUSINESS_ACCOUNT_ID: es un ID distinto para la WABA propietaria del número, usado por la llamada de suscripción de la Causa 2, y es facilísimo intercambiar los dos al copiarlos del dashboard.

Dos trampas extra que conviene descartar

Si las cuatro causas de arriba están limpias y los mensajes siguen sin fluir, revisa esto:

La app está atascada en modo Dev. WhatsApp solo entrega webhooks de mensajes que el propietario de la app haya enviado o recibido en las últimas 24 horas, y solo desde números añadidos explícitamente en WhatsApp luego API Setup luego To. Pasa la app a Live en App Review cuando estés lista para tráfico real.
El campo webhook messages no está suscrito. En WhatsApp luego Configuration, mira la sección Webhook fields y confirma que messages tiene un tick verde. Meta te deja guardar una URL de webhook sin campos suscritos, y silenciosamente no entrega nada.

Orden de diagnóstico que ahorra tiempo

Cuando el bot enmudezca, atraviesa las causas en este orden en vez de reinstalarlo todo:

¿Estás en el camino QR? Si sí, migra a la Cloud API antes de gastar un minuto más en cualquier otra cosa. Shortcake no se va a ir.
¿Tu WABA está suscrita a tu app? La única llamada curl de arriba lo contesta en tres segundos. La tasa de acierto más alta en despliegues de Cloud API.
Comprueba el token. curl /me falla al instante si el token está muerto, es incorrecto o le faltan permisos.
Verifica el Phone Number ID. curl /$PHONE_NUMBER_ID devuelve los campos del número cuando es válido.
Revisa el modo Dev y los campos suscritos. Más lento de inspeccionar, menos común como causa raíz, pero merece descartarse antes de abrir un ticket con Meta.

Para la instalación inicial completa de WhatsApp, revisa la guía de despliegue de Hermes Agent en WhatsApp. Si Telegram te encaja, la comparación Telegram vs WhatsApp recorre los tradeoffs antes de comprometerte.

Cuando prefieres no pelearte con Meta cada semana

Meta lanza cambios en la UI del webhook, endurece la verificación y rompe el camino QR a su propio ritmo. Si tu lectura es que un agente de IA personal no debería exigir una cuenta de Business Manager y un token de System User para responder hola, empieza con Hermify. Hermify ejecuta un Hermes Agent gestionado en Telegram con la misma memoria y las mismas skills, activo en cerca de un minuto, sin la configuración de Meta que vigilar.