Skip to main content

🔧 Operational Troubleshooting

Resolve the most common issues without escalating to the technical team.

Quick diagnostic tree​

Is the problem...?
├── The bot doesn't respond       → Section 1
├── The bot responds incorrectly  → Section 2
├── Leads/notifs not arriving     → Section 3
├── Payment/plan error            → Section 4
├── WhatsApp not working          → Section 5
├── Dashboard shows an error      → Section 6
├── Bookings not appearing        → Section 7
└── Social media / Facebook       → Section 8

Section 1 — The bot doesn't respond​

P1.1 The bot doesn't respond in the web chat​

SymptomProbable causeSteps
Chat loads but does not send messagesWidget JavaScript blockedVerify that the embed snippet is correctly installed and check the browser console for JS errors
"Hotel not found"Incorrect hotel_id in the widgetGo to Connections → Web Widget → Embed code, copy the updated code and replace it on the site
Infinite spinner when opening the chatCORS issue or backend URL problemEscalate to L2 Support with a screenshot and the site URL
The widget does not appear on the siteSnippet not installed or blocked by ad-blockerVerify that the code is in the HTML before </body> and test in incognito mode (no extensions)

P1.2 The bot doesn't respond on WhatsApp​

SymptomProbable causeSteps
Messages don't reach the numberNumber disconnectedGo to Connections → WhatsApp Business, verify that the status reads connected; if it reads disconnected, reconnect by entering the 360dialog credentials
Bot responds only to some messagesPlan limit reachedSee Hotels → [your hotel] → Billing → Usage; if at the limit, buy an add-on pack
Bot takes more than 5 secondsMeta API latencyWait 10 minutes; if it persists, escalate to L2
"Number not enabled for WhatsApp Business API"Number not migrated to Business APIContact 360dialog to migrate the number

Section 2 — The bot responds incorrectly​

P2.1 The bot gives incorrect hotel information​

SymptomProbable causeSolution
Incorrect pricesRates not updatedGo to Rates and Availability and update base or seasonal prices
Incorrect check-in/out timesField not configuredGo to Hotels → [your hotel] → Policies and update
The bot says there is no parking but there isMissing information in RAGGo to AI Training → Missing Information and add the answer to that specific question
The bot describes a room that no longer existsRoom still active in the systemGo to Hotels → [your hotel] → Rooms and mark the room as inactive or delete it

P2.2 The bot doesn't show images​

SymptomProbable causeSolution
"I don't have any photos available"Images not uploaded or incorrect namesGo to AI Training → Images, verify that images are uploaded and rename them using the format type-space-number (e.g.: suite-1, piscina-principal)
Images uploaded but the bot doesn't show themThe guest's keyword doesn't match the nameUpload the same image with multiple alias names (e.g.: habitacion-doble-1, cuarto-double-1)

P2.3 The bot speaks in the wrong language​

The bot automatically detects the guest's language and responds in the same language. If this fails:

  • The fallback is the default language configured in Hotels → [your hotel] → Settings
  • If the default language is set to English but your market is Spanish-speaking: change it to Spanish

P2.4 The bot tries to make a direct booking but the hotel is Freemium​

Correct behavior on Freemium: the bot generates a pre-booking (captures the guest's data and sends it to the hotel for manual confirmation). This is not an error — it is the expected behavior of the free plan.

If you want the bot to make automatic direct bookings: upgrade to the Matrix plan and connect a PMS (LobbyPMS, Hossrom, FNS Rooms or Erbon).

Section 3 — Leads and notifications not arriving​

P3.1 Leads captured but no notification​

CauseVerificationSolution
Notification channel not configuredHotels → [your hotel] → Notifications: must have an email or WhatsApp enteredEnter an email address or WhatsApp number to receive alerts
WhatsApp not configured on FreemiumThe hotel had no channels configuredConfigure at least email notifications
Notification email in spamCheck the spam folderAdd noreply@hotelchatbook.io to safe contacts

P3.2 The lead appears in the panel but without complete data​

The bot captures data progressively during the conversation. If the guest left before providing all their details, the lead remains incomplete. This is normal behavior — the bot does not force the guest to provide information before responding.

Section 4 — Payment and plan issues​

:::tip Known bug (resolved) UAI-383 — the Error 500 in the subscription checkout flow was resolved in Sprint 1. If you see a 500 error, refresh the page and retry. :::

P4.1 Error when trying to upgrade the plan​

ErrorCauseSolution
"Error 500 when starting checkout"Intermittent Stripe bugRefresh and retry; if it persists, contact support
"Your plan reverted to Freemium"Failed Stripe paymentGo to Hotels → [your hotel] → Billing → Update payment method → Retry
Overage not billed correctlyBug in the conversation counterEscalate to L2 with screenshots of the counter

P4.2 Incorrect conversation counter​

If the counter shows a number that does not match actual activity:

  1. Go to Hotels → [your hotel] → Billing → Period usage
  2. Check the billing_cycle_start_date — the counter resets from that date
  3. If the number is still incorrect: escalate to L2 with the hotel_id and the expected vs. displayed number

Section 5 — WhatsApp not working​

P5.1 The number appears as disconnected​

  1. Go to Connections → WhatsApp Business
  2. Click "Reconnect"
  3. Re-enter the 360dialog credentials (account_sid + auth_token)
  4. If the error persists: verify that the number is still active in the 360dialog panel

P5.2 Message templates are rejected by Meta​

Meta may reject templates due to aggressive marketing content, excessive use of capital letters, or links without a verified domain.

Solution: review the Meta Business guidelines for templates and rephrase the content. The approval process takes 24–48 hours.

P5.3 The number is in "opt-out"​

If a guest blocked the number or marked the message as spam, their opt_in_status changes to opted_out. The bot cannot contact that number again. This is correct behavior and required by Meta.

Section 6 — Dashboard shows errors​

P6.1 Dashboard shows zeros even though there is activity​

:::tip Known bug (resolved) UAI-382 — resolved in Sprint 1. If you see zeros, refresh the page. :::

If after refreshing it still shows zeros for a hotel with real activity: escalate to L2 with the hotel_id.

P6.2 I can't see the [Module] section​

Verify that your user has the correct role:

  • hotel_employee cannot see billing or settings
  • hotel_admin has full access

If you have the correct role and it still doesn't appear: it could be a plan feature gate. Check in Hotels → [your hotel] → Billing whether the module requires a higher plan.

P6.3 The page loads but is blank​

  1. Clear the browser cache (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac)
  2. Try another browser
  3. If it persists: escalate to L2

Section 7 — Bookings not appearing​

P7.1 The booking was created in the chat but doesn't appear in the panel​

Requires:

  • An active Matrix or Pro plan
  • A connected PMS (LobbyPMS, Hossrom, FNS Rooms or Erbon)
  • An active PMS connection at the time of booking

Verify in PMS Integration that the status is connected.

P7.2 The booking appears but without a payment status​

The payment flow is external:

  1. The bot creates the booking in the PMS
  2. The Notificator sends a payment link to the guest via email/WhatsApp
  3. The guest pays externally (Stripe link)
  4. The Stripe webhook updates the payment status

If the status does not update within more than 1 hour: escalate to L2 with the booking_id.

Section 8 — Social Media (Facebook / Instagram)​

info

The social media integration requires a platform administrator to activate the connection. Hoteliers cannot connect it directly from the panel.

P8.1 Facebook/Instagram messages don't appear in Conversations​

CauseSolution
The integration is not activated for your hotelContact UNOZERO support to activate the social channel
The Facebook page is not connected to the Business accountVerify that the Business account has access to the page from Meta Business Suite
Expired Meta tokenEscalate to L2 — the Meta token needs to be re-authenticated

P8.2 The bot responds in the web chat but not on Instagram​

Automatic AI replies on Instagram and Facebook require additional configuration in Meta Business Suite (auto-reply enabled). If the bot does not respond automatically on these channels, the message still arrives in the Conversations inbox for manual reply.

Escalation — when to call the technical team​

LevelWho resolves itWhen to escalate
L1 — Self-resolutionHotel Admin follows this guideIssues covered in sections 1–8
L2 — UNOZERO SupportSupport teamPersistent 500 errors, incorrect data in the DB, undocumented bugs
L3 — DevelopmentDevelopment teamConfirmed bugs that require code, integration errors with external APIs

How to report an issue to L2​

Always include:

  • hotel_id (visible in the dashboard URL)
  • A description of the error with steps to reproduce it
  • A screenshot or screen recording
  • The exact time and date of the incident
  • The hotel's current plan (Freemium / Matrix / Pro / Pro Unlimited)

Support channel: JSM (Jira Service Management) — link available in the dashboard → "Help".