Docs / 3. Conectividad & Canales

Canal WhatsApp & Webhooks

Integración oficial de WhatsApp Business, canal directo del dueño y gobernanza de plantillas.

Canal WhatsApp & Webhooks

WhatsApp es el canal de comunicación por excelencia para la atención al cliente, reservas hoteleras y coordinación operativa. Orbis integra la API oficial de WhatsApp Business (Cloud API / Zernio) bajo un esquema de seguridad fail-closed, gobernanza de plantillas y canal bidireccional de control para el dueño.

┌─────────────────────────────────────────────────────────────┐
│                 ARQUITECTURA DE WHATSAPP                    │
├─────────────────────────────────────────────────────────────┤
│ 1. INGESTA VERIFICADA          Firma criptográfica HMAC-256 │
│ 2. CANAL DEL CLIENTE           Atención 24/7 y cotizaciones │
│ 3. CANAL DEL DUEÑO             Aprobaciones y comandos      │
│ 4. WATCHDOG DE SALUD           Detección de billing y drops │
└─────────────────────────────────────────────────────────────┘

---

1. Ingesta Criptográfica de Webhooks

Toda petición entrante desde los servidores de Meta o Zernio se valida antes de despertar al motor de ejecución:

  • Verificación de Firma: Cada webhook debe incluir su cabecera de autenticación (X-Hub-Signature-256 o X-Zernio-Signature). Si la firma no coincide con el secreto configurado en el vault, el servidor rechaza el paquete con código 503 Service Unavailable.
  • Allowlist Fail-Closed: Para entornos de prueba o pilotos cerrados, Orbis restringe la recepción a números autorizados (WHATSAPP_ALLOWED_USERS), descartando cualquier tráfico no reconocido antes de consumir capacidad.
  • Deduplicación de Envíos: La red móvil puede reintentar mensajes idénticos. Cada mensaje entrante se registra con su ID de mensaje único (wamid), previniendo respuestas duplicadas.

---

2. Plantillas Oficiales (Templates) & Apertura en Frío

Cuando la empresa necesita contactar a un cliente fuera de la ventana de 24 horas (por ejemplo, para enviar una confirmación de reserva 3 días antes de la llegada o una notificación de vuelo retrasado):

  • Gestión de Plantillas: Orbis valida que la plantilla esté aprobada por Meta antes de intentar el envío.
  • Pre-Gate Local: Si una plantilla fue pausada o rechazada en el Business Manager de Meta (PAUSED, REJECTED), el gate local frena la emisión, evitando penalizaciones de calidad y cobros innecesarios.
  • Egress DLP en Parámetros: Las variables dinámicas de la plantilla (nombre, fecha, monto) son escaneadas por el motor de prevención de pérdida de datos antes de viajar a Meta.

---

3. El Canal del Dueño (Owner Channel)

El dueño o gerente de la empresa no necesita estar frente a una computadora para autorizar gastos o conocer el estado de su operación. Orbis vincula su número personal de WhatsApp como canal de comando seguro:

ORBIS ──► "🚨 Solicitud de Aprobación [APR-842]:
           El huésped Carlos Pérez solicita cancelación con reembolso del 100%
           (Monto: $120.000). Política estándar: no reembolsable.
           Respondé 'sí' para autorizar o 'no' para rechazar."

DUEÑO ──► "sí"

ORBIS ──► "✅ Aprobado. El reembolso se procesó y se notificó al huésped."

Comandos Interactivos del Dueño

Además de autorizar transacciones, el canal del dueño es interactivo y responde a comandos directos en lenguaje natural:

Comando Acción de Orbis
estado Reporte resumido del día: reservas atendidas, ocupación actual y % de tu plan usado en el mes.
incidentes Lista de alertas operativas o de sistemas que requieran atención inmediata.
pendientes Lista de solicitudes 4-Eyes aguardando respuesta del dueño.
pausar [rol] Pausa temporal de las rutinas de un empleado específico.
ayuda Despliega el menú de comandos autorizados para el número del dueño.

---

4. Vigilancia de Salud del Canal (Watchdog)

La caída inadvertida de una línea de WhatsApp Business puede costar miles de dólares en reservas perdidas. Orbis incluye un supervisor de canal (Channel Watchdog):

  • Incidentes de Facturación (waba_billing): Si la tarjeta asociada a la cuenta de Meta expira o rechaza un pago, el sistema detecta el error y deriva un incidente crítico de inmediato al dueño.
  • Suspensiones de Meta (waba_suspended): Notifica en tiempo real si la cuenta de WhatsApp Business experimentó un bloqueo temporal por políticas.
  • Estado de Envío (wa_send_status): Monitorea eventos delivered y read para verificar que los mensajes alcancen efectivamente el teléfono de los clientes.