🔧 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:
- Ir a Hoteles → [tu hotel] → Facturación → Uso del período
- Verificar el
billing_cycle_start_date— el contador se reinicia desde esa fecha - Si el número sigue incorrecto: escalar a L2 con el
hotel_idy el número esperado vs. mostrado
Sección 5 — WhatsApp no funciona
P5.1 El número aparece como desconectado
- Ve a Conexiones → WhatsApp Business
- Haz clic en «Reconectar»
- Ingresa nuevamente las credenciales de 360dialog (
account_sid+auth_token) - 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_employeeno puede ver facturación ni configuraciónhotel_admintiene 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
- Limpiar caché del navegador (Ctrl+Shift+R en Windows, Cmd+Shift+R en Mac)
- Probar en otro navegador
- 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:
- El bot crea la reserva en el PMS
- El Notificator envía link de pago al huésped vía email/WhatsApp
- El huésped paga externamente (link de Stripe)
- 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)
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».