Guest Messaging

Overview

WhatsApp, Instagram, and Facebook Messenger are the dominant guest communication channels in hospitality markets. Guest Messaging provides a single workspace where staff can manage all guest conversations — whether handled by the automated booking bot or by human agents.

Key Capabilities

• Unified inbox — All conversations from all channels in one three-panel view
• Automated booking bot — Guests browse availability, select rooms, and confirm bookings entirely within the messaging app
• Agent handover — Bot detects when it can't help and escalates to a human agent with full context
• Channel adapters — Same booking flow works across WhatsApp, Instagram, and Messenger with automatic message type degradation
• AI-powered NLU — Natural language understanding via Claude Haiku for freeform guest messages
• Canned responses — Pre-written reply templates for agents with shortcuts and categories
• Conversation notes — Internal notes visible only to staff

Supported Channels

Message Costs (WhatsApp)

The Unified Inbox

The inbox is a three-panel workspace designed for managing multiple conversations simultaneously:

Left Panel — Conversation List

• Search by guest name or phone number
• Filter by channel (WhatsApp, Instagram, Messenger), status, or assigned agent
• Each conversation shows: guest name, last message preview, timestamp, channel icon, unread badge
• Status dots: green = bot handling, orange = awaiting agent, blue = agent assigned, gray = resolved
• Sorted by most recent message, auto-refreshes every 3 seconds

Center Panel — Message Thread

• Full message history grouped by date
• Message bubbles: guest messages (left), bot messages (center-left), agent messages (right)
• System messages for events: "Bot escalated to agent", "Agent claimed conversation", etc.
• Action buttons in header: Claim, Assign, Resolve, Hand Back to Bot
• Message composer with canned response picker
• Status banners: "Bot is handling" with Take Over button, "Waiting for agent" with Claim button

Right Panel — Guest Detail

• Guest profile: name, phone, channel, profile picture
• Linked trading partner (if identified)
• Reservation history
• Internal conversation notes (visible only to staff)
• Quick actions: Create Reservation, View Guest Profile

Agent Handover

The system seamlessly transfers conversations between the automated bot and human agents.

Conversation Statuses

When Does the Bot Escalate?

• Guest requests it — Messages containing "human", "agent", "help", "speak to someone", "real person", "staff", or "reception" trigger an escalation offer
• Low AI confidence — When the AI can't understand the guest's intent (confidence below 50%) outside of an active booking flow
• Repeated failures — After 3 consecutive messages the bot can't understand, it automatically escalates without asking

For the first two triggers, the bot offers the guest a choice: "Talk to our team" or "Continue with assistant". The third trigger escalates directly.

Agent Actions

• Claim — Take ownership of an AWAITING_AGENT conversation. The system also auto-assigns to the least-loaded online agent when possible.
• Assign — Transfer a conversation to another agent (requires messaging:manage permission)
• Resolve — Mark the conversation as resolved. The next guest message will start a fresh bot conversation.
• Hand back to bot — Return the conversation to automated handling. The bot will greet the guest on the next message.

Agent Status

Agents set their status in the messaging module header:

• Online — Available for auto-assignment. The system routes new escalations to the agent with the fewest active conversations.
• Away — Not available for new assignments, but can still manage existing conversations
• Offline — Not available. Existing conversations stay assigned.

Timeouts

• Bot conversations: 60 minutes of inactivity → auto-expire to idle
• AWAITING_AGENT: 30 minutes with no agent claim → revert to bot handling

Connecting a Channel

Qvian is a Meta Tech Provider — your clients connect their WhatsApp, Instagram, or Messenger accounts with a single click. No developer accounts, API tokens, or webhook configuration required.

One-Click Setup (Recommended)

1. Go to Guest Messaging → Connections
2. Click Add Channel
3. Select the channel type (WhatsApp, Instagram, or Messenger)
4. Optionally set a connection name and greeting message
5. Click Connect with Meta
6. A Facebook Login popup opens — log in and authorize Qvian to access your business account
7. For WhatsApp: select or create your WhatsApp Business Account and register a phone number
8. For Instagram/Messenger: select the Facebook Page to connect
9. The popup closes and your channel appears as CONNECTED — done!

Behind the scenes, Qvian automatically exchanges tokens, discovers your business assets, subscribes to webhooks, and registers phone numbers. Token refresh is handled automatically before expiration.

Advanced Setup (Manual Credentials)

For edge cases (self-hosted deployments, firewall restrictions, or if you manage your own Meta developer app), click Advanced Setup in the Add Channel dialog. This requires manually entering a Phone Number ID, WABA ID, access token, and app secret. See Meta's documentation for how to obtain these credentials.

Testing the Connection

1. Send a message from any WhatsApp phone to the connected business number
2. You should receive a greeting message with interactive buttons within a few seconds
3. Check the Inbox tab to see the conversation appear
4. If no reply comes, check the Troubleshooting section below

Token Lifecycle

Tokens obtained via Embedded Signup expire after approximately 60 days. Qvian automatically refreshes tokens 7 days before expiration via a daily background job. If a token cannot be refreshed (e.g., the user revoked access), the channel status changes to ERRORand staff are notified. Re-authorize by clicking Connect with Meta again.

WhatsApp Payment Method

WhatsApp Cloud API requires a payment method for template message charges (service messages during booking conversations are free). The business owner should add a credit card in Meta Business Settings → Billing & Payments. Without this, outbound template messages will fail.

Automated Booking Flow

The booking bot guides guests through a structured conversation using interactive messages:

1. Greeting

When a guest sends any message, they receive a welcome message with three interactive buttons:

• Book a Stay — Start the booking process
• Check Availability — Browse available rooms
• My Reservations — Look up existing bookings

Guests can also skip the buttons and type a freeform message like "I'd like a room for 2 nights starting tomorrow". AI understands the intent and can even extract dates from the same message, skipping straight to availability results.

2. Collecting Dates

The guest provides check-in date, check-out date, and number of guests. They can type dates in YYYY-MM-DD format or use natural language like "tomorrow for 3 nights" or "March 15 to 18 for 2 adults" — AI will resolve relative dates automatically.

3. Showing Availability

Available rooms are displayed as an interactive list message (on WhatsApp) or numbered text (on channels that don't support lists). Each row shows the room name, nightly rate, and currency.

4. Guest Information

If the guest is not already known (matched by phone number), the system asks for their first name, last name, and email address. Known guests skip this step.

5. Confirmation

A booking summary is shown with three buttons: Confirm, Change, and Cancel.

6. Booking Created

On confirmation, a reservation is created in the PMS through the standard reservation pipeline — all accounting, tax, and resource allocation flows are inherited automatically. The guest receives a confirmation message with the booking reference number, and staff receive an in-app notification.

Conversation Timeout

If a guest stops responding for 60 minutes, the conversation is automatically reset. They can start over by sending any new message.

Message Templates

WhatsApp requires pre-approved message templates for outbound notifications sent outside the 24-hour customer-initiated window. The Templates tab lets you map Meta-approved templates to internal events.

Supported Events

Creating a Template Mapping

1. Create and get your template approved in the Meta Business Manager
2. Go to Guest Messaging → Templates
3. Click Add Template
4. Select the channel connection, enter the exact template name from Meta
5. Select the event type and language
6. Set the parameter mapping — which template variables map to which reservation fields

Parameter Mapping

The parameter mapping is a JSON object that maps template variable positions to reservation data paths. For example, if your Meta template has 3 body parameters:

{
  "1": "guestName",
  "2": "checkIn",
  "3": "reference"
}

Canned Responses

Canned responses are pre-written reply templates that agents can quickly insert when responding to guests. Manage them from Guest Messaging → Settings.

• Title — Display name shown in the picker
• Content — The actual message text
• Shortcut — Quick-access keyword (e.g. /checkin)
• Category — Group responses by topic (e.g. "Booking", "Check-in", "General")

In the message composer, click the canned response button to browse available responses, or type a shortcut to filter. Click a response to insert it into the composer — you can edit it before sending.

Connection Statuses

Webhook Security

All incoming webhooks are verified using Meta's signature mechanism:

1. Meta sends the X-Hub-Signature-256 header with each webhook POST
2. The system computes HMAC-SHA256 of the raw request body using the App Secret
3. Signatures are compared using crypto.timingSafeEqual() to prevent timing attacks
4. Invalid signatures are rejected with 401

Each message includes a unique platform message ID used for idempotency — duplicate messages are ignored.

Troubleshooting

Webhook verification fails

• Verify the Callback URL is correct and accessible from the internet
• Verify the Verify Token matches exactly (copy from the connection detail page)
• Ensure your server is reachable on HTTPS (Meta requires SSL)

Messages not being received

• Check that the connection status is CONNECTED
• Verify the webhook is subscribed to the messages field in Meta Dashboard
• Check the App Secret is correct (signature verification may be failing silently)
• Look at server logs for webhook signature errors

Template messages not sending

• Verify the template is approved in Meta Business Manager
• Verify the template name in the mapping matches exactly (case-sensitive)
• Check that the language code matches the approved template language
• Verify the parameter count matches what the template expects

Booking not created

• Check that rooms are available for the selected dates
• Verify the business unit has services configured with pricing
• Look at server logs for reservation creation errors
• The conversation may have timed out (60 min) — the guest needs to start over

Agent not receiving escalations

• Check that at least one agent has status set to Online in the messaging module
• Verify the agent's active conversations count is below their max conversations limit
• If no agents are online, the conversation stays in AWAITING_AGENT — the guest sees "Our team will respond shortly"

Guest not receiving replies

• Verify the access token is valid and not expired
• Check Meta API error logs in server output
• For template messages: ensure you are within Meta's messaging limits for your tier
• For service messages: ensure the reply is within 24 hours of the customer's last message

Related

• Reservations — Where messaging bookings appear after creation
• Hotel Front Desk — Check-in/out messaging guests
• Service Management — Define room types shown to guests
• Channel Manager — OTA integrations for broader distribution
• Public Booking API — REST API for web-based booking