MANUAL

Qué es WhatsApp Enterprise?

WhatsApp Enterprise (Meta Business API) es la API OFICIAL de Meta/Facebook para integrar WhatsApp en aplicaciones empresariales. A diferencia de soluciones no oficiales como Baileys, esta API:

• Tiene soporte oficial de Meta
• Garantiza 99.9% de disponibilidad (SLA)
• No tiene riesgo de ban por automatización
• Permite enviar mensajes masivos con templates aprobados

Diferencia con Baileys

Cuándo usar Meta Enterprise?

• Tienes un negocio legalmente constituido
• Necesitas atención al cliente 24/7
• Quieres enviar notificaciones/campañas masivas
• El costo por mensaje es viable para tu negocio

Requisitos de Negocio

• Empresa legalmente constituida
• Sitio web activo de la empresa
• Política de privacidad publicada
• Número de teléfono dedicado (no usado en WhatsApp personal)

Requisitos Técnicos

• Servidor con IP pública
• Certificado SSL válido (HTTPS obligatorio)
• Puerto 7071 accesible desde Internet
• Fararoni Core instalado y funcionando
• Java 25+ con --enable-preview

Cuentas Necesarias

• Cuenta de Facebook personal (del administrador)
• Cuenta de Meta for Developers
• WhatsApp Business Account (se crea durante el proceso)

Cifrado de Canales

# Producción (recomendado para WhatsApp Enterprise)
export FARARONI_CHANNELS_ENCRYPTION_KEY="$(openssl rand -base64 32)"
export FARARONI_ENV=production
java --enable-preview -jar fararoni-core-1.0.0.jar --server

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

Paso 3.1: Crear App en Meta for Developers

1. Ir a https://developers.facebook.com
2. Click en "My Apps" → "Create App"
3. Seleccionar tipo: "Business"
4. Nombre: "Fararoni WhatsApp" (o el nombre de tu empresa)
5. Click "Create App"

Paso 3.2: Agregar WhatsApp a la App

1. En el Dashboard, buscar "WhatsApp"
2. Click "Set Up"
3. Meta te guiará para crear un WhatsApp Business Account

Paso 3.3: Verificar tu Negocio

1. Ir a Meta Business Suite → Settings → Business Info
2. Completar: nombre legal, dirección, sitio web, documentos (RFC, acta constitutiva)
3. Esperar aprobación (1-5 días hábiles)

Paso 3.4: Registrar Número de Teléfono

1. En WhatsApp → API Setup → "Add Phone Number"
2. Ingresar el número dedicado
3. Verificar vía SMS o llamada
4. Guardar el Phone Number ID

Paso 3.5: Token de Acceso Permanente

1. Business Settings → Users → System Users
2. Click "Add" → Nombre: "Fararoni API"
3. Asignar permisos: whatsapp_business_messaging, whatsapp_business_management
4. Generar Token

El token de System User no expira. El token de usuario normal expira en 60 días.

Paso 3.6: Configurar Webhook

1. En WhatsApp → Configuration → Webhook
2. Callback URL: https://tu-servidor.com:7071/gateway/v1/meta/webhook
3. Verify Token: Un string secreto (ej: mi_token_secreto_123)
4. Click "Verify and Save"

Paso 3.7: Suscribirse a Eventos

En "Webhook fields", suscribirse a: messages (obligatorio). Opcional: message_template_status_update.

Paso 4.1: Variables de Entorno

# WhatsApp Enterprise - Meta Business API
export META_VERIFY_TOKEN="mi_token_secreto_123"
export META_ACCESS_TOKEN="EAAGm0PX4ZCps..."
export META_PHONE_ID="123456789012345"

source ~/.bashrc  # o ~/.zshrc

Paso 4.2: Editar modules.yml

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

gateway:
  rest:
    enabled: true
    port: 7071

  meta:
    enabled: true
    verify_token: "env:META_VERIFY_TOKEN"
    access_token: "env:META_ACCESS_TOKEN"
    phone_id: "env:META_PHONE_ID"
    api_version: "v18.0"

channels:
  whatsapp:
    enabled: false  # Desactivar Baileys

  whatsapp_meta:
    enabled: true
    trust_level: SECURE_ENTERPRISE
    egress_adapter: "meta_enterprise"
    capabilities:
      - text
      - template
    timeout_ms: 10000
    retry_count: 3

Paso 4.3: Reiniciar Fararoni

pkill -f fararoni-core
cd fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

Verificar Logs de Inicio

[MODULE-REGISTRY] Loaded module: OmniChannelGatewayModule
[INGRESS] RestIngressServer listening on port 7071
[META-ENTERPRISE] Meta webhook endpoint registered: /gateway/v1/meta/webhook
[META-EGRESS] Initialized for phone: 123456789012345

Verificación Automática

Cuando configuras el webhook en Meta, envía una petición GET:

GET /gateway/v1/meta/webhook?hub.mode=subscribe&hub.challenge=1234567890&hub.verify_token=mi_token_secreto_123

Fararoni debe responder con el número del hub.challenge.

Verificación Manual

curl "https://tu-servidor.com:7071/gateway/v1/meta/webhook?hub.mode=subscribe&hub.challenge=test123&hub.verify_token=mi_token_secreto_123"

Respuesta esperada: test123

Enviar Mensaje de Prueba (desde Meta)

1. En Meta for Developers → WhatsApp → API Setup
2. En "Send and receive messages", hay un número de prueba
3. Agregar tu número personal como destinatario de prueba
4. Enviar mensaje de prueba

Recibir Mensaje en Fararoni

Desde tu WhatsApp personal, envía un mensaje al número Enterprise. Verificar en logs:

[META-WEBHOOK] Received message from: 5212291234567
[OmniChannel] Processing message: "Hola"
[OmniChannel] Response sent to: 5212291234567

Error: "Webhook verification failed"

1. Verificar que META_VERIFY_TOKEN coincida exactamente
2. Verificar que el puerto 7071 sea accesible desde Internet
3. Verificar certificado SSL

Error: "Invalid OAuth access token"

Token expirado o incorrecto. Regenerar token en Meta for Developers, actualizar META_ACCESS_TOKEN y reiniciar.

Error: "Phone number not registered"

El Phone ID no corresponde al número verificado. Copiar el correcto desde Meta for Developers → WhatsApp → Phone Numbers.

Los mensajes no llegan a Fararoni

1. El webhook está suscrito a messages
2. El firewall permite tráfico al puerto 7071
3. El servidor tiene certificado SSL válido

tail -f ~/.fararoni/logs/fararoni.log | grep META

El robot no responde

Verificar: mensaje llega al bus (agency.input.whatsapp), OmniChannelRouter procesa, egress funciona ([META-EGRESS]).

Modelo de Precios de Meta (2026)

Meta cobra por conversación, no por mensaje individual:

Ventana de 24 horas

Si el usuario inicia la conversación, tienes 24 horas para responder GRATIS. Después de 24 horas, solo puedes enviar templates aprobados (con costo).

Templates (Mensajes Masivos)

1. Crear template en Meta Business → WhatsApp → Message Templates
2. Esperar aprobación (1-24 horas)
3. Usar desde Fararoni:

metaAdapter.sendTemplate("5212291234567", "welcome_message", "es");

Facturación

Meta factura mensualmente. Se requiere método de pago (tarjeta de crédito). Puedes configurar alertas de gasto en Meta Business Suite.

Checklist de Implementación

PRE-REQUISITOS
[ ] Empresa legalmente constituida
[ ] Sitio web con política de privacidad
[ ] Número de teléfono dedicado
[ ] Servidor con HTTPS y puerto 7071 abierto

META BUSINESS
[ ] App creada en Meta for Developers
[ ] WhatsApp Business Account creado
[ ] Negocio verificado
[ ] Número registrado
[ ] Token de System User generado
[ ] Webhook configurado y verificado
[ ] Suscripción a evento "messages"

FARARÓNI
[ ] Variables de entorno configuradas
[ ] modules.yml actualizado
[ ] gateway.meta.enabled: true
[ ] channels.whatsapp_meta.enabled: true
[ ] Fararoni reiniciado

PRUEBAS
[ ] Webhook verification exitosa
[ ] Mensaje de prueba recibido
[ ] Respuesta enviada correctamente

Comandos Útiles

# Ver logs en tiempo real
tail -f ~/.fararoni/logs/fararoni.log | grep -E "(META|WHATSAPP)"

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

# Ver variables de entorno
echo $META_ACCESS_TOKEN | head -c 20
echo $META_PHONE_ID
echo $META_VERIFY_TOKEN

Autor: Equipo Fararoni | Versión: 1.0