🔧 Troubleshooting Operativo

Resuelve los problemas más comunes sin escalar al equipo técnico.

Árbol de diagnóstico rápido

¿El problema es...?
├── El bot no responde         → Sección 1
├── El bot responde mal        → Sección 2
├── No llegan leads/notifs     → Sección 3
├── Error en pagos/plan        → Sección 4
├── WhatsApp no funciona       → Sección 5
├── Dashboard muestra error    → Sección 6
├── Reservas no aparecen       → Sección 7
└── Redes sociales / Facebook  → Sección 8

Sección 1 — El bot no responde

P1.1 El bot no responde en el web chat

Síntoma	Causa probable	Pasos
Chat carga pero no envía mensajes	JavaScript del widget bloqueado	Verificar que el snippet de embed está correctamente instalado y revisar la consola del navegador por errores JS
«Hotel no encontrado»	hotel_id incorrecto en el widget	Ir a Conexiones → Widget Web → Código de embed, copiar el código actualizado y reemplazarlo en el sitio
Spinner infinito al abrir el chat	Problema de CORS o URL del backend	Escalar a Soporte L2 con screenshot y URL del sitio
El widget no aparece en el sitio	Snippet no instalado o bloqueado por ad-blocker	Verificar que el código está en el HTML antes de </body> y probar en modo incógnito (sin extensiones)

P1.2 El bot no responde en WhatsApp

Síntoma	Causa probable	Pasos
Mensajes no llegan al número	Número desconectado	Ir a Conexiones → WhatsApp Business, verificar que el estado dice connected; si dice disconnected, reconectar ingresando credenciales 360dialog
Bot responde solo a algunos mensajes	Límite de plan alcanzado	Ver Hoteles → [tu hotel] → Facturación → Consumo; si está al límite, comprar paquete adicional
Bot tarda más de 5 segundos	API de Meta con latencia	Esperar 10 minutos; si persiste, escalar a L2
«Número no habilitado para WhatsApp Business API»	Número no migrado a Business API	Contactar a 360dialog para migrar el número

Sección 2 — El bot responde incorrectamente

P2.1 El bot da información incorrecta del hotel

Síntoma	Causa probable	Solución
Precios incorrectos	Tarifas no actualizadas	Ir a Tarifas y Disponibilidad y actualizar precios base o de temporada
Horarios de check-in/out incorrectos	Campo no configurado	Ir a Hoteles → [tu hotel] → Políticas y actualizar
El bot dice que no tiene parqueadero pero sí hay	Información faltante en RAG	Ir a Entrenamiento IA → Información Faltante y agregar la respuesta a esa pregunta específica
El bot describe una habitación que ya no existe	Habitación activa en el sistema	Ir a Hoteles → [tu hotel] → Habitaciones y marcar la habitación como inactiva o eliminarla

P2.2 El bot no muestra imágenes

Síntoma	Causa probable	Solución
«No tengo fotos disponibles»	Imágenes no subidas o nombres incorrectos	Ir a Entrenamiento IA → Imágenes, verificar que hay imágenes subidas y renombrar con formato tipo-espacio-numero (ej: suite-1, piscina-principal)
Imágenes subidas pero el bot no las muestra	El keyword del huésped no coincide con el nombre	Subir la misma imagen con múltiples nombres de alias (ej: habitacion-doble-1, cuarto-double-1)

P2.3 El bot habla en el idioma incorrecto

El bot detecta automáticamente el idioma del huésped y responde en el mismo idioma. Si esto falla:

• El fallback es el idioma por defecto configurado en Hoteles → [tu hotel] → Configuración
• Si el idioma por defecto está en inglés pero tu mercado es hispanohablante: cambiarlo a Español

P2.4 El bot intenta hacer una reserva directa pero el hotel es Freemium

Comportamiento correcto en Freemium: el bot genera una pre-reserva (captura datos del huésped y los envía al hotel para confirmación manual). No es un error — es el comportamiento esperado del plan gratuito.

Si quieres que el bot haga reservas directas automáticas: actualizar a plan Matrix y conectar PMS (LobbyPMS, Hossrom, FNS Rooms o Erbon).

Sección 3 — No llegan leads ni notificaciones

P3.1 Leads capturados pero sin notificación

Causa	Verificación	Solución
Canal de notificación no configurado	Hoteles → [tu hotel] → Notificaciones: debe tener email o WhatsApp ingresado	Ingresar correo o número de WhatsApp para recibir alertas
WhatsApp sin configurar en Freemium	El hotel no tenía canales configurados	Configurar al menos notificación por email
Email de notificación en spam	Revisar carpeta de spam	Agregar noreply@hotelchatbook.io a contactos seguros

P3.2 El lead aparece en el panel pero sin datos completos

El bot captura los datos progresivamente durante la conversación. Si el huésped salió antes de dar todos sus datos, el lead queda incompleto. Esto es comportamiento normal — el bot no obliga al huésped a dar información antes de responder.

Sección 4 — Problemas con pagos y plan

:::tip Bug conocido (resuelto) UAI-383 — el Error 500 en el flujo de checkout de suscripción fue resuelto en Sprint 1. Si ves un error 500, refresca la página y reintenta. :::

P4.1 Error al intentar actualizar el plan

Error	Causa	Solución
«Error 500 al iniciar checkout»	Bug intermitente en Stripe	Refrescar y reintentar; si persiste, contactar soporte
«Tu plan volvió a Freemium»	Pago de Stripe fallido	Ir a Hoteles → [tu hotel] → Facturación → Actualizar método de pago → Reintentar
No se factura el excedente correctamente	Bug en contador de conversaciones	Escalar a L2 con capturas del contador

P4.2 Contador de conversaciones incorrecto

Si el contador muestra un número que no corresponde a la actividad real:

1. Ir a Hoteles → [tu hotel] → Facturación → Uso del período
2. Verificar el billing_cycle_start_date — el contador se reinicia desde esa fecha
3. Si el número sigue incorrecto: escalar a L2 con el hotel_id y el número esperado vs. mostrado

Sección 5 — WhatsApp no funciona

P5.1 El número aparece como desconectado

1. Ve a Conexiones → WhatsApp Business
2. Haz clic en «Reconectar»
3. Ingresa nuevamente las credenciales de 360dialog (account_sid + auth_token)
4. Si el error persiste: verificar que el número sigue activo en el panel de 360dialog

P5.2 Las plantillas de mensaje son rechazadas por Meta

Meta puede rechazar plantillas por contenido de marketing agresivo, uso de mayúsculas excesivas o links sin dominio verificado.

Solución: revisar las guías de Meta Business para plantillas y reformular el contenido. El proceso de aprobación toma 24–48 horas.

P5.3 El número está en «opt-out»

Si un huésped bloqueó el número o marcó el mensaje como spam, su opt_in_status pasa a opted_out. El bot no puede volver a contactar a ese número. Esto es comportamiento correcto y requerido por Meta.

Sección 6 — Dashboard muestra errores

P6.1 Dashboard muestra ceros aunque hay actividad

:::tip Bug conocido (resuelto) UAI-382 — resuelto en Sprint 1. Si ves ceros, refresca la página. :::

Si después de refrescar sigue mostrando ceros en un hotel con actividad real: escalar a L2 con el hotel_id.

P6.2 No puedo ver la sección de [Módulo]

Verificar que tu usuario tiene el rol correcto:

• hotel_employee no puede ver facturación ni configuración
• hotel_admin tiene acceso completo

Si tienes el rol correcto y sigue sin aparecer: podría ser un feature gate de plan. Verificar en Hoteles → [tu hotel] → Facturación si el módulo requiere un plan superior.

P6.3 La página carga pero está en blanco

1. Limpiar caché del navegador (Ctrl+Shift+R en Windows, Cmd+Shift+R en Mac)
2. Probar en otro navegador
3. Si persiste: escalar a L2

Sección 7 — Reservas no aparecen

P7.1 La reserva fue creada en el chat pero no aparece en el panel

Requiere:

• Plan Matrix o Pro activo
• PMS conectado (LobbyPMS, Hossrom, FNS Rooms o Erbon)
• Conexión PMS activa en el momento de la reserva

Verificar en Integración PMS que el estado es connected.

P7.2 La reserva aparece pero sin estado de pago

El flujo de pago es externo:

1. El bot crea la reserva en el PMS
2. El Notificator envía link de pago al huésped vía email/WhatsApp
3. El huésped paga externamente (link de Stripe)
4. El webhook de Stripe actualiza el estado de pago

Si el estado no se actualiza en más de 1 hora: escalar a L2 con el booking_id.

Sección 8 — Redes Sociales (Facebook / Instagram)

info

La integración de redes sociales requiere que un administrador de plataforma active la conexión. Los hoteleros no pueden conectarla directamente desde el panel.

P8.1 Los mensajes de Facebook/Instagram no aparecen en Conversaciones

Causa	Solución
La integración no está activada para tu hotel	Contactar soporte UNOZERO para que active el canal social
La página de Facebook no está conectada a la cuenta Business	Verificar que la cuenta Business tiene acceso a la página desde Meta Business Suite
Token de Meta caducado	Escalar a L2 — se requiere reautenticación del token de Meta

P8.2 El bot responde en el chat web pero no en Instagram

La respuesta automática por IA en Instagram y Facebook requiere configuración adicional en Meta Business Suite (auto-respuesta habilitada). Si el bot no responde automáticamente en estos canales, el mensaje llega igualmente a la bandeja de Conversaciones para respuesta manual.

Escalamiento — cuándo llamar al equipo técnico

Nivel	Quién resuelve	Cuándo escalar
L1 — Auto-resolución	Hotel Admin sigue esta guía	Problemas cubiertos en las secciones 1–8
L2 — Soporte UNOZERO	Equipo de soporte	Errores 500 persistentes, datos incorrectos en DB, bugs no documentados
L3 — Desarrollo	Equipo de desarrollo	Bugs confirmados que requieren código, errores de integración con APIs externas

Cómo reportar un problema a L2

Incluir siempre:

• hotel_id (visible en la URL del dashboard)
• Descripción del error con pasos para reproducirlo
• Screenshot o grabación de pantalla
• Hora y fecha exacta del incidente
• Plan actual del hotel (Freemium / Matrix / Pro / Pro Unlimited)

Canal de soporte: JSM (Jira Service Management) — link disponible en el dashboard → «Ayuda».