MANUAL

Qué es WhatsApp Baileys?

Baileys es una librería no oficial de código abierto que permite conectar a WhatsApp Web desde Node.js. Es completamente GRATUITA y no requiere ninguna cuenta de negocio ni verificación.

Arquitectura

+----------------+     +-----------------+     +----------------+     +----------------+
|   Usuario      | --> |  WhatsApp Web   | --> |   Sidecar WA   | --> |   Fararoni     |
|   WhatsApp     |     |  (Baileys)      |     |   (:3000)      |     |   Gateway      |
+----------------+     +-----------------+     +----------------+     |   (:7071)      |
                                                                      +----------------+
                                                                             |
                                                                             v
                                                                      +----------------+
                                                                      |  Agentes LLM   |
                                                                      +----------------+

Ventajas

Limitaciones (Advertencia)

IMPORTANTE: Para producción empresarial, usa WhatsApp Enterprise.

Cuándo usar Baileys?

• Desarrollo y pruebas locales
• Proyectos personales
• POCs (Proof of Concept)
• Cuando no puedes pagar WhatsApp Enterprise
• Bots de uso moderado (no spam)

Software Necesario

• Node.js 20 o superior
• npm (viene con Node.js)
• Fararoni Core instalado
• Java 25+ con --enable-preview

WhatsApp

• Celular con WhatsApp instalado y funcionando
• Número de teléfono activo en WhatsApp
• El celular debe tener conexión a Internet

Puertos

# Verificar Node.js (debe ser 20+)
node --version

# Verificar npm
npm --version

# Verificar Java
java --version

Cifrado de Canales

# Desarrollo local
export FARARONI_DEV_MODE=true
# La key se genera automáticamente

cd /ruta/a/fararoni/fararoni-sidecar-wa
npm install

Esto instalará: @whiskeysockets/baileys, express, axios, qrcode-terminal

Verificar modules.yml

Ubicación: ~/.fararoni/config/modules.yml

channels:
  whatsapp:
    enabled: true
    trust_level: UNTRUSTED_EXTERNAL
    egress_url: "http://localhost:3000/send"
    capabilities:
      - text
      - audio
      - image
    timeout_ms: 5000
    retry_count: 3

Gateway REST

gateway:
  rest:
    enabled: true
    port: 7071

Orden de Inicio (IMPORTANTE)

1. Fararoni Core (Gateway)  <-- PRIMERO
2. Sidecar WhatsApp         <-- SEGUNDO

Terminal 1: Iniciar Fararoni Core

cd /ruta/a/fararoni/fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

Esperar hasta ver:

[MODULE-REGISTRY] Loaded module: OmniChannelGatewayModule
[INGRESS] RestIngressServer listening on port 7071

Terminal 2: Iniciar Sidecar WhatsApp

cd /ruta/a/fararoni/fararoni-sidecar-wa
npm start

La primera vez, verás un código QR en la terminal.

Ver el QR en Terminal

█████████████████████████████████████
█████████████████████████████████████
████ ▄▄▄▄▄ █▀█ █▄ ▀▄█▀▄█ ▄▄▄▄▄ ████
████ █   █ █▀▀▀█  ▄▄▀ ▄█ █   █ ████
...
[INFO] Escanea el código QR con tu WhatsApp

Abrir WhatsApp en el Celular

1. Abre WhatsApp en tu celular
2. Toca los tres puntos (menú) en la esquina superior derecha
3. Selecciona "Dispositivos vinculados"
4. Toca "Vincular un dispositivo"
5. Apunta la cámara al QR en la terminal

Verificar Conexión Exitosa

[INFO] Conexión establecida
[INFO] Sesión guardada en ./baileys_auth_info/
[INFO] WhatsApp conectado. Listo para recibir mensajes.

La Sesión se Guarda

La sesión se guarda en fararoni-sidecar-wa/baileys_auth_info/. La próxima vez NO necesitarás escanear de nuevo.

Cuándo Expira la Sesión

Cómo Re-autenticar

cd fararoni-sidecar-wa && rm -rf baileys_auth_info && npm start

Eliminar baileys_auth_info/ fuerza una autenticación limpia desde cero, ya que las credenciales locales quedan desincronizadas con el servidor de WhatsApp.

Health Check del Gateway

curl http://localhost:7071/gateway/v1/health
# {"status": "healthy", "module": "gateway-rest-omnichannel"}

Health Check del Sidecar

curl http://localhost:3000/health
# {"status": "connected", "phone": "+522291234567"}

Prueba End-to-End

1. Desde otro teléfono, envía un mensaje a tu número de WhatsApp
2. Deberías recibir una respuesta automática de Fararoni

Verificar Logs

[INGRESS] +522299876543 -> "Hola, necesito ayuda"
[EGRESS] +522299876543 <- "Hola! Soy Fararoni, en que puedo ayudarte?"

Filtro de Grupos

Por defecto, el sidecar SOLO responde a chats privados (1:1).

Cómo Funciona el Filtro

if (remoteJid.endsWith('@g.us')) {
    console.log('[FILTRO] Ignorando mensaje de grupo:', remoteJid);
    return;
}

Habilitar Grupos Específicos

const ALLOWED_GROUPS = [
    '123456789-1234567890@g.us',
    '987654321-0987654321@g.us'
];

if (remoteJid.endsWith('@g.us') && !ALLOWED_GROUPS.includes(remoteJid)) {
    return;
}

Riesgo de Ban

Recomendaciones: Usa Baileys solo para desarrollo y pruebas. Para producción, considera WhatsApp Enterprise. No hagas spam.

El QR no aparece

rm -rf baileys_auth_info
npm start

Error "Session closed" o "Connection Failure"

Causa: La sesión de WhatsApp expiró o fue invalidada.

cd fararoni-sidecar-wa && rm -rf baileys_auth_info && npm start

Luego escanea el nuevo QR.

Error "ECONNREFUSED"

Causa: El Gateway no está corriendo.

java --enable-preview -jar fararoni-core-1.0.0.jar --server

El bot no responde

# Verificar Gateway
curl http://localhost:7071/gateway/v1/health

# Verificar Sidecar
curl http://localhost:3000/health

Si el health dice "disconnected", elimina la sesión y escanea QR de nuevo.

WhatsApp pide vincular de nuevo

rm -rf baileys_auth_info
npm start
# Escanear QR de nuevo

Error "Número baneado"

1. Esperar 24-72 horas y reintentar
2. Apelar el ban desde WhatsApp
3. Usar otro número
4. Considerar WhatsApp Enterprise (sin riesgo de ban)

Health Checks

# Gateway
curl http://localhost:7071/gateway/v1/health

# Sidecar WhatsApp
curl http://localhost:3000/health

# Ver QR actual
curl http://localhost:3000/qr

Resetear Sesión

cd fararoni-sidecar-wa
rm -rf baileys_auth_info
npm start

Detener Servicios

pkill -f "fararoni-core"
pkill -f "fararoni-sidecar-wa"

Variables de Entorno

Checklist de Implementación

REQUISITOS
[ ] Node.js 20+ instalado
[ ] Fararoni Core instalado
[ ] Java 25+ con --enable-preview
[ ] Celular con WhatsApp

INSTALACIÓN
[ ] npm install ejecutado
[ ] modules.yml tiene whatsapp.enabled: true

PUESTA EN MARCHA
[ ] Gateway corriendo en puerto 7071
[ ] Sidecar corriendo en puerto 3000
[ ] Código QR visible en terminal

VINCULACIÓN
[ ] QR escaneado desde WhatsApp
[ ] Sesión guardada en baileys_auth_info/

PRUEBAS
[ ] Health checks OK
[ ] Mensaje enviado desde otro celular
[ ] Respuesta recibida

Diferencias con Enterprise

Autor: Equipo Fararoni | Versión: 1.0