Novedades en la Configuración de WhatsApp en Hermes

Si has seguido nuestra serie sobre el Agente Hermes, sabes que nos encanta simplificar las cosas. Hoy nos adentramos en la configuración actualizada de WhatsApp, y hay un gran cambio bajo el capó.

Hermes ahora se conecta a WhatsApp mediante un puente integrado basado en Baileys. Piénsalo como si emulara una sesión de WhatsApp Web. Sin cuenta de desarrollador de Meta, sin verificación de negocio, sin URL pública — solo tú, tu teléfono y un código QR.

Inicio rápido: Ejecuta hermes gateway setup y elige WhatsApp para obtener una guía paso a paso.

Dos Integraciones de WhatsApp — Conoce la Diferencia

Antes de continuar, aclaremos un punto de confusión común. Hay dos formas de conectar WhatsApp a Hermes:

Integración	Ideal para	Requiere
Puente Baileys (esta guía)	Bots personales, pruebas rápidas, sin URL pública	Solo un teléfono con WhatsApp
API de WhatsApp Business Cloud	Bots de negocio reales, estabilidad, riesgo cero de bloqueo	Cuenta de negocio de Meta, URL pública de webhook

El puente Baileys es no oficial — conlleva un pequeño riesgo de bloqueo. La API de Business Cloud es la vía oficial respaldada por Meta. Incluso puedes ejecutar ambas en paralelo con diferentes números de teléfono si lo necesitas.

⚠️ Dos Advertencias Importantes

Riesgo de bloqueo: WhatsApp no admite oficialmente bots de terceros fuera de la API de negocio. Para mantenerte a salvo:

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

Actualizaciones del protocolo: WhatsApp actualiza periódicamente su protocolo web, lo que puede interrumpir temporalmente los puentes de terceros. Si tu bot deja de funcionar después de una actualización de WhatsApp, simplemente descarga la última versión de Hermes y vuelve a vincularlo.

Dos Modos — Elige tu Estilo

Modo	Cómo funciona	Ideal para
Número de bot separado (recomendado)	Dedica un número al bot; las personas le escriben directamente	UX limpia, múltiples usuarios, menor riesgo de bloqueo
Chat personal contigo mismo	Usa tu propio WhatsApp; escríbete a ti mismo para hablar con el agente	Configuración rápida, un solo usuario, pruebas

Requisitos Previos

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

Buenas noticias: el puente actual basado en Baileys ya no requiere Chromium ni Puppeteer. Mucho más ligero.

Paso 1: Ejecuta el Asistente de Configuración

hermes whatsapp

El asistente:

Preguntará qué modo quieres (bot o chat personal)
Instalará las dependencias del puente si es necesario
Mostrará un código QR en tu terminal
Esperará a que lo escanees

Para escanear el código QR:

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

Una vez vinculado, el asistente confirma la conexión y finaliza. 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 admita Unicode.

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. Tres opciones:

Opción	Costo	Notas
Google Voice	Gratis	Solo EE. UU. Verifica WhatsApp por SMS a través de la aplicación de Google Voice.
SIM prepago	$5–15 único pago	Actívala, verifica, y luego la SIM puede quedarse en un cajón. Haz una llamada cada 90 días para mantenerla activa.
Servicios VoIP	Gratis–$5/mes	TextNow, TextFree, etc. Algunos números están bloqueados por WhatsApp — prueba varios.

Después de obtener el número:

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

Paso 3: Configura Hermes

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

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

# Control de acceso — elige UNA opción:
WHATSAPP_ALLOWED_USERS=15551234567         # Números separados por comas (código de país, sin +)
# WHATSAPP_ALLOWED_USERS=*                 # O permite a todos
# WHATSAPP_ALLOW_ALL_USERS=true            # O establece esta bandera (igual que *)

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

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair (predeterminado global) envía un código de vinculación a remitentes desconocidos por mensaje directo.
ignore mantiene a WhatsApp en silencio para mensajes directos no autorizados — generalmente mejor para un número privado.

Luego inicia la puerta de enlace:

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

Persistencia de Sesión y Re-vinculación

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

Las sesiones sobreviven a los reinicios — sin necesidad de re-escanear cada vez
Los datos de sesión incluyen claves de cifrado y credenciales del dispositivo
No compartas ni subas este directorio — otorga acceso completo a la cuenta

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. Soluciónalo ejecutando:

hermes whatsapp

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

Eso es todo sobre la nueva configuración de WhatsApp en pocas palabras. Rápida, ligera y sin papeleo de Meta. Lo próximo en la serie: compararemos este puente lado a lado con la API de WhatsApp Business Cloud — ¡mantente atento!