Web Chat

Lodgestory CRM › Settings → Connections → Web Chat

Drop a branded chat widget on any website and land the conversation in the same inbox as WhatsApp, Email, and Instagram.

TL;DR

• What it is — a floating chat widget you embed with a single snippet. Visitors chat with a bot journey, a human agent, or both, from any page on your site.
• Who it's for — Account Owners and Admins configure the widget. Anyone visiting the site can chat in. Team members answer from the unified inbox.
• Top outcome — every website visitor can start a real conversation in the browser — and it lands in the same inbox as every other channel.

At a glance

How to find it

Sidebar: Settings → Connections → Web Chat (nested under Connections).

Direct URL: https://app.lodgestory.com/crm/settings/connections/webwidget

[SCREENSHOT: web-chat-landing.png — list of configured widgets with status]

What is Web Chat?

The problem it solves

Chat is the lowest-friction inbound channel on the internet — if it's connected to the rest of your operation. Most chat widgets are silos: messages in a widget inbox, tickets in another tool, the CRM somewhere else. Team members context-switch; customers repeat themselves three times; the data never fully reconciles.

Web Chat is a first-class inbound channel inside the same Lodgestory inbox that handles WhatsApp, Instagram, Email, and voice calls. Messages land in Home with a contact attached, a bot journey routing the reply if you've set one, and the same ticket-creation and agent-assignment you use everywhere else.

What you get

• Admin configuration for every part of the widget. Theme (colour, logo, position), welcome greeting, teaser nudge, audio cues, offline message, business hours, pre-chat form, allowed domains, upload limits.
• Copy-paste install for popular stacks. Plain HTML, React, Next.js, Vue, Nuxt, Svelte, Angular, WordPress, and Shopify each get a ready-made snippet on the install tab.
• Bot journey per widget. Same pattern as every other channel — pick a deployed journey and a bot identity, save, and the widget starts replying.
• Secret rotation with a 24-hour grace. When you rotate the widget's secret, the old one stays valid for 24 hours so existing site deployments keep working while you roll out the new snippet. After 24 hours, only the new secret works.
• Domain allowlist with wildcards. List the domains where the widget is allowed to load. A wildcard like *.example.com matches every subdomain without listing each.
• The same message types as every other channel. Visitors can send text, images, and files. Agents and bots can send text, media, interactive buttons, lists, location, and call-to-action links — the widget renders them all.
• Live delivery. Messages arrive instantly, with typing indicators and read receipts.
• Offline form. When no agent is available (or it's outside your business hours), the widget collects the visitor's contact and a single message, and the team picks it up on the next shift.
• Server-side uploads. Visitors upload files through Lodgestory rather than directly to a third-party store, which keeps your domain allowlist simple and the flow safe.
• Per-session rate limits. Abuse protection is built in — 30 messages a minute per chat session, 10 new session opens a minute per visitor, 60 ephemeral events a minute per session.

How it's different

• Full bot-journey parity with WhatsApp. Every bot journey step works on Web Chat. Buttons render as buttons, lists render as lists, call-to-action links are clickable. You don't rebuild flows for the web.
• Secret rotation with a 24-hour grace. No downtime when you rotate. Roll out the new snippet on your sites over the window, and everyone lands on the new secret cleanly.
• Wildcards in the origin allowlist. Running 40 subsites under *.example.com? List the wildcard once.
• Style isolation. The widget renders inside its own styled environment, so your site's CSS can't leak into it and the widget can't leak out.

Customer scenarios

• Marketing site with pre-chat form. An Admin turns on a pre-chat form asking for name, email, and reason. The visitor fills it, chats, and the fields are already attached to their contact record when a team member picks it up.
• Multi-brand agency. An agency runs 40 subsites under *.example-group.com. One widget, the wildcard listed once, a single embed snippet deployed via the shared head-tag include.
• Rotating a leaked secret. A staff laptop is stolen. Admin rotates the widget's secret. Live sessions continue for up to 24 hours on the old secret; during that window the Admin rolls out the new snippet across all sites. After 24 hours the old secret is dead.
• Outside business hours. A visitor arrives at 2 AM. The widget switches to the offline form, collects their details plus one message, and agents pick it up the next morning as a new chat.

How it fits with the rest of Lodgestory CRM

Web Chat is nested under Connections and shows up as a channel everywhere the platform talks about channels:

• Home / Unified Inbox — widget chats land here with a Web Chat badge.
• Bot Journeys — per-widget journey assignment.
• Contacts — pre-chat form responses seed new contacts.
• Campaigns — Web Chat doesn't support outbound broadcasts, but chat-initiated flows are standard.

Core concepts

Quick Start — embed Web Chat on your website in 5 minutes

Step 1 — Open Web Chat and create a widget

Settings → Connections → Web Chat → + New Widget.

[SCREENSHOT: web-chat-qs-1-create.png]

Step 2 — Configure

• Display name — an internal label (e.g. Marketing site widget).
• Theme — primary colour, logo upload (up to 1 MB), widget position (bottom-left or bottom-right).
• Welcome message — the first line the visitor sees.
• Teaser — an optional popup text that nudges the visitor to open the chat.
• Allowed origins — the domains where this widget can embed. Wildcards like *.example.com supported.
• Pre-chat form — toggle on if you want to collect name, email, or phone before chatting.
• Business hours — optional weekly grid.
• Offline message and offline form — what to show outside business hours.
• Max upload size — 1 KB to 50 MB (default 10 MB).

Save — the widget is created and a secret is generated.

Step 3 — Assign a bot journey (optional)

Same pattern as other channels — pick a deployed journey, pick a bot identity, save.

Step 4 — Copy the embed snippet

The widget detail page has an Install Instructions tab with snippets for nine popular stacks. Here's the plain-HTML version:

<script>
  window.LodgestoryWebChat = {
    widgetId: "your-widget-id",
    secret: "your-widget-secret"
  };
</script>
<script async src="https://app.lodgestory.com/webwidget.js"></script>

Paste it before </body> on every page where you want the widget to appear.

[SCREENSHOT: web-chat-qs-4-snippet.png]

Step 5 — Verify

Reload the site. A widget button appears in the position you configured. Click it, send a message, and the conversation lands in the unified inbox.

Step 6 (optional) — Rotate the secret

When you need to rotate (a departed developer, a suspected leak), click Rotate Secret on the widget card. The old secret stays valid for 24 hours while you update your snippet across sites.

What's next

• Build a bot journey for the widget → Bot Journeys
• Style the widget using its CSS custom properties → see the Install Instructions tab

How it works

Every widget is a separate row of configuration with its own secret, its own domain allowlist, and optionally its own bot journey. When a visitor opens the widget, the embedded bundle opens a session with Lodgestory, confirms the origin matches the allowlist, validates the secret, and issues the visitor a signed session token stored in their browser's local storage. Reloading the page keeps them in the same conversation.

Messages from the visitor hit Lodgestory's public endpoint. Lodgestory validates the origin, the session token, and the request rate, creates or updates the contact, stores the conversation, and fans the message out to the right bot journey or directly to agents in the unified inbox. Agent replies travel back the same way, arriving in the widget in real time.

Uploads go through Lodgestory — the visitor uploads a file, Lodgestory checks the type and size against the widget's configuration, stores it, and returns a URL the chat can reference. The visitor never talks directly to object storage, which keeps the domain allowlist small and the flow consistent.

When you rotate a secret, the old secret is preserved alongside the new one for 24 hours. Every request is accepted against either. Past 24 hours, only the new secret works. This gives you a zero-downtime window to update the snippet on your sites.

Features in depth

Widget cards

Each widget shows its display name, current status, the bot journey assigned, the domain allowlist count, and actions — Edit, Rotate Secret, Delete.

Configuration form

Theme and branding. Primary colour, logo, position, button shape.

Behaviour. Welcome message, teaser, pre-chat form (name, email, phone, toggled per-field), business-hours grid, offline message and offline form, idle timeout, session time-to-live.

Audio cues. Toggle for incoming-message sound; upload a custom sound or use the default.

Security. Allowed origins with wildcard support; max upload size.

Journey assignment

Same pattern as other channels — one live bot journey, one bot identity. See Bot Journeys.

Install Instructions

Nine tabs covering plain HTML, React, Next.js, Vue, Nuxt, Svelte, Angular, WordPress, and Shopify. Each tab also shows CSS custom properties you can override to match your brand.

Rotate Secret

On the widget card, click Rotate Secret. A confirmation dialog shows the new embed snippet; the old secret remains valid for 24 hours. The card displays a grace-period timer so you know how long you have to roll out the new snippet.

File uploads

The widget's upload goes through Lodgestory, which validates the file type and size against the widget's configuration before storing it. Size limits are configurable per widget (default 10 MB).

Offline form

When business hours are set and the visitor arrives outside them, the widget automatically switches to offline-form mode. The submission creates a chat visible to agents the next time they log in.

Allowed origins with wildcards

Permit an entire group of subdomains with *.example.com — foo.example.com and bar.example.com match, but example.com on its own does not. Add both entries for full coverage.

Roles and permissions

Cross-module workflows

A. Visitor → bot triage → human agent

Visitor opens the widget, submits the pre-chat form, asks a question. The bot journey classifies and answers the simple cases; anything non-trivial hits an Agent Transfer step and lands in the unified inbox with an Agent transferred banner for a team member to pick up.

B. Multi-tenant agency

An agency manages 40 subsites under *.example-group.com. A single widget with the wildcard in its allowed origins. One snippet deployed via a shared head-tag include. Every site's chat lands in the same inbox.

C. Out-of-hours fallback

Outside business hours, the widget switches to the offline form. Submissions land as new chats; agents see them on the next shift.

Limits a user will run into

Errors and FAQ

Errors you might see

FAQ

How do I use the widget on multiple subdomains?
Add *.your-domain.com to the allowed origins. One widget works across every subdomain.

What happens to in-flight chats when I rotate the secret?
Nothing, for the first 24 hours. Live sessions on the old secret continue working. After 24 hours only the new secret works, so finish rolling out the new snippet before the grace window ends.

My widget shows but messages don't send.
Usually an origin allowlist issue. Check the page's origin (including protocol) is in the widget's allowed origins.

Can I style the widget with my site's CSS?
Not directly — the widget renders in its own isolated environment, which protects both sides. It exposes CSS custom properties you can set on the host element to override colours, fonts, and spacing. The full list is on the Install Instructions tab.

Can visitors send files?
Yes, provided the widget has uploads enabled and the file is an allowed type within the size limit. Uploads go through Lodgestory rather than a third-party store.

How do I keep a visitor's conversation across page reloads?
It's automatic. The widget stores the session token in local storage on the visitor's browser. When they reload, they pick up where they left off.

What happens if I delete a widget that has active sessions?
Live sessions end cleanly, widgets embedded on customer sites show a friendly message, and the chats become read-only in the inbox.

Can agents start a chat with a visitor first?
No — Web Chat is visitor-initiated. Once a visitor has opened the conversation, the agent can reply, but there's no way to ping a visitor who hasn't opened the widget. Use WhatsApp or Email for proactive outbound.

API

An admin API handles widget configuration and secret rotation. A public API is what the embedded widget calls from the visitor's browser. Contact your account team for access if you need to build a custom client; the snippet is the supported path for everyone else.

Changelog

• Apr 2026 — Initial public documentation.

Related modules and next steps

• Connections — the parent page where Web Chat is nested.
• Home / Unified Inbox — where widget chats land.
• Bot Journeys — per-widget journey assignment.
• Contacts — pre-chat form fields seed new contacts.