WhatsApp — IA para el Chat Más Usado del Mundo

WhatsApp está en todas partes. Más de dos mil millones de personas lo usan a diario, y ahora puedes conectar Hermes directamente. Sin cuenta de desarrollador de Meta. Sin verificación de negocio. Sin configuración complicada de API. Solo escanea un código QR y ya estás hablando con tu agente de IA desde la misma app que usas para mensajear con tus amigos.

Cómo Funciona

Hermes se conecta a WhatsApp mediante un puente integrado basado en Baileys. Piénsalo como emular una sesión de WhatsApp Web — de la misma manera en que vincularías un navegador a tu teléfono. No es la API oficial de WhatsApp Business, lo que significa que no necesitas ninguna aprobación especial para empezar.

Ejecuta hermes gateway setup y elige WhatsApp para una guía paso a paso.

Dos Formas de Usarlo

Modo	Cómo funciona	Ideal para
Número de bot separado (recomendado)	Dedica un número de teléfono al bot. La gente le escribe directamente a ese número.	UX limpia, múltiples usuarios, menor riesgo de bloqueo
Auto-chat personal	Usa tu propio WhatsApp. Te mensajeas a ti mismo para hablar con el agente.	Configuración rápida, un solo usuario, pruebas

El enfoque de número de bot separado es más limpio — tu IA tiene su propia identidad y no mezclas chats personales con conversaciones del bot. El modo auto-chat es perfecto para una prueba rápida.

Antes de Empezar

Necesitarás:

Node.js v18+ y npm — el puente de WhatsApp se ejecuta como un proceso de Node.js
Un teléfono con WhatsApp instalado (para escanear el código QR)

Buena noticia: a diferencia de los puentes antiguos basados en navegador, no necesitas Chromium ni Puppeteer instalados. La configuración es mucho más ligera.

Paso 1: Ejecuta el Asistente de Configuración

hermes whatsapp

El asistente:

Pregunta qué modo quieres (bot o auto-chat)
Instala las dependencias del puente si es necesario
Muestra un código QR en tu terminal
Espera a que lo escanees

Para escanear el código QR:

Abre WhatsApp en tu teléfono
Ve a Configuración → Dispositivos vinculados
Toca Vincular un dispositivo
Apunta tu cámara al código QR del terminal

Una vez vinculado, el asistente confirma la conexión y sale. Tu sesión se guarda automáticamente.

Consejo: Si el código QR se ve distorsionado, asegúrate de que tu terminal tenga al menos 60 columnas de ancho y soporte Unicode. También puedes probar con otro emulador de terminal.

Paso 2: Obtener un Segundo Número de Teléfono (Modo Bot)

Para el modo bot, necesitas un número que no esté ya registrado en WhatsApp. Estas son tus opciones:

Opción	Costo	Notas
Google Voice	Gratis	Solo EE. UU. Obtén un número en voice.google.com. Verifica WhatsApp por SMS a través de la app de Google Voice.
SIM prepago	$5–15 único pago	Cualquier operador. Activa, verifica WhatsApp, y luego la SIM puede quedarse en un cajón. El número debe mantenerse activo (haz una llamada cada 90 días).
Servicios VoIP	Gratis–$5/mes	TextNow, TextFree o similares. Algunos números VoIP están bloqueados por WhatsApp — prueba varios si el primero no funciona.

Después de obtener el número:

Instala WhatsApp en un teléfono (o usa la app de WhatsApp Business con doble SIM)
Registra el nuevo número con WhatsApp
Ejecuta hermes whatsapp y escanea el código QR desde esa cuenta de WhatsApp

Paso 3: Configurar Hermes

Añade lo siguiente a tu archivo ~/.hermes/.env:

# Requerido
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" o "self-chat"

# Control de acceso — elige UNA de estas opciones:
WHATSAPP_ALLOWED_USERS=15551234567         # Números de teléfono separados por comas (con código de país, sin +)
# WHATSAPP_ALLOWED_USERS=*                 # O usa * para permitir a todos
# WHATSAPP_ALLOW_ALL_USERS=true            # O establece esta bandera en su lugar (mismo efecto que *)

Atajo para permitir a todos: Establecer WHATSAPP_ALLOWED_USERS=* permite a todos los remitentes. Para usar el flujo de vinculación en su lugar, elimina ambas variables y confía en el sistema de vinculación por MD.

Configuración opcional de comportamiento en ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair es el valor predeterminado global. Los remitentes de MD desconocidos reciben un código de vinculación.
whatsapp.unauthorized_dm_behavior: ignore hace que WhatsApp permanezca en silencio para MD no autorizados — generalmente la mejor opción para un número privado.

Luego inicia el gateway:

hermes gateway              # En primer plano
hermes gateway install      # Instalar como servicio de usuario
sudo hermes gateway install --system   # Solo Linux: servicio del sistema al arrancar

El gateway inicia el puente de WhatsApp automáticamente usando la sesión guardada.

Persistencia de Sesión

El puente de Baileys guarda su sesión en ~/.hermes/platforms/whatsapp/session. Esto significa:

Las sesiones sobreviven a los reinicios — no necesitas volver a escanear el código QR cada vez
Los datos de sesión incluyen claves de cifrado y credenciales del dispositivo
No compartas ni subas este directorio de sesión — otorga acceso completo a la cuenta de WhatsApp

Re-vinculación

Si la sesión se rompe (restablecimiento del teléfono, actualización de WhatsApp, desvinculación manual), verás errores de conexión en los registros del gateway. Para solucionarlo:

hermes whatsapp

Esto genera un código QR nuevo para re-vincular.

Una Palabra de Precaución

WhatsApp no soporta oficialmente bots de terceros fuera de la API Business. Usar un puente de terceros conlleva un pequeño riesgo de restricciones en la cuenta. Para minimizar el riesgo:

Usa un número de teléfono dedicado para el bot (no tu número personal)
No envíes mensajes masivos/spam — mantén el uso conversacional
No automatices mensajes salientes a personas que no te han escrito primero

Además, WhatsApp actualiza periódicamente su protocolo Web, lo que puede romper temporalmente la compatibilidad con puentes de terceros. Cuando esto ocurra, Hermes actualizará la dependencia del puente. Si el bot deja de funcionar después de una actualización de WhatsApp, descarga la versión más reciente de Hermes y vuelve a vincular.

¿Quieres Algo Más Oficial?

Si estás ejecutando un bot de negocio real y quieres estabilidad, consulta la guía de la API Cloud de WhatsApp Business en su lugar. Es el camino oficial respaldado por Meta: sin riesgo de bloqueo de cuenta, pero requiere una cuenta de negocio de Meta y una URL de webhook pública. Los dos adaptadores también pueden ejecutarse en paralelo contra diferentes números de teléfono si tienes una razón para ello.

Para la mayoría de proyectos personales y experimentos, sin embargo, el puente de Baileys es la forma más rápida de llevar IA a tu WhatsApp. Escanea, configura y empieza a chatear.