# 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

|                          |                                                                                                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan tiers**           | All paid tiers.                                                                                                                                      |
| **Who can use it**       | Admins configure and rotate the widget. Site visitors chat in. Team members answer from the inbox.                                                   |
| **Channel relationship** | Web Chat is itself a channel, listed alongside WhatsApp, Instagram, Messenger, and Email. You can assign a bot journey to it like any other channel. |
| **Integrations**         | Live message delivery, file uploads, and the standard bot-journey flow.                                                                              |
| **Top limits**           | One live bot journey per widget. Configurable maximum file size per upload (1 KB to 50 MB, default 10 MB). Per-session rate limits to prevent abuse. |
| **API**                  | Yes — admin API for configuration and secret rotation; a public API that the embedded widget calls from visitor browsers.                            |

## 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](connections.md) and shows up as a channel everywhere the platform talks about channels:

* **[Home / Unified Inbox](../workspace/home-unified-inbox.md)** — widget chats land here with a Web Chat badge.
* **[Bot Journeys](bot-journeys.md)** — per-widget journey assignment.
* **[Contacts](../workspace/contacts.md)** — pre-chat form responses seed new contacts.
* **[Campaigns](../workspace/campaigns.md)** — Web Chat doesn't support outbound broadcasts, but chat-initiated flows are standard.

## Core concepts

| Term                 | What it means                                                                                                                                       |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Widget**           | A single chat embed with its own theme, secret, domain allowlist, and bot journey.                                                                  |
| **Secret**           | The value that authorises your website to talk to Lodgestory on behalf of this widget. Rotate when needed; the old secret stays valid for 24 hours. |
| **Domain allowlist** | The exact origins where the widget is allowed to load. Supports wildcards like `*.example.com`.                                                     |
| **Pre-chat form**    | An optional form shown to the visitor the first time they open the widget.                                                                          |
| **Business hours**   | A weekly grid that controls when the widget is live versus when it switches to an offline form.                                                     |
| **Offline form**     | The fallback form shown outside business hours or when no agent is available.                                                                       |
| **Session**          | A single visitor's conversation on the widget. Survives page reloads using the browser's local storage.                                             |

## 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:

```html
<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](bot-journeys.md)
* 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](bot-journeys.md).

### 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

| Action                                | Account Owner | Admin |        User       | Visitor |
| ------------------------------------- | :-----------: | :---: | :---------------: | :-----: |
| Create, edit, or delete a widget      |      Yes      |  Yes  |         No        |    —    |
| Rotate a secret                       |      Yes      |  Yes  |         No        |    —    |
| Assign a bot journey                  |      Yes      |  Yes  |         No        |    —    |
| Open a chat session                   |       —       |   —   |         —         |   Yes   |
| Send messages                         |       —       |   —   |         —         |   Yes   |
| See widget chats in the unified inbox |      Yes      |  Yes  | Yes (if assigned) |    —    |

## 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

| Limit                           | Value                         |
| ------------------------------- | ----------------------------- |
| Widgets per organisation        | Plan-tier based               |
| Allowed origins per widget      | No practical cap              |
| Max upload per widget           | 1 KB to 50 MB (default 10 MB) |
| Session open                    | 10 per minute per visitor IP  |
| Messages                        | 30 per minute per session     |
| Ephemeral events (typing, read) | 60 per minute per session     |
| Secret rotation grace           | 24 hours                      |

## Errors and FAQ

### Errors you might see

| Message                                              | What it means                                                                                    | What to do                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| *Origin not allowed*                                 | The page's domain isn't in the widget's allowed origins.                                         | Add the origin (with or without wildcard) to the widget configuration.            |
| *Invalid session token*                              | Often happens when the secret rotation grace window has passed and the site hasn't been updated. | Copy the new snippet from the admin UI onto the site.                             |
| *Too many requests*                                  | The rate limit kicked in.                                                                        | The widget backs off automatically; if you're hitting this in testing, slow down. |
| *File too large*                                     | The file exceeds the widget's max upload.                                                        | Use a smaller file or raise the widget's limit.                                   |
| *Unsupported file type*                              | The file type isn't allowed.                                                                     | Only image, video, and standard document types are allowed.                       |
| *Widget not found*                                   | The widget ID in the snippet is wrong or the widget was deleted.                                 | Recopy the snippet from the admin UI.                                             |
| *Failed to save widget*                              | A configuration validation or save error.                                                        | Read the inner message and adjust.                                                |
| *Secret rotated. Update your sites within 24 hours.* | Informational — the grace window started.                                                        | Copy the new snippet across every site before it expires.                         |

### 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](connections.md) — the parent page where Web Chat is nested.
* [Home / Unified Inbox](../workspace/home-unified-inbox.md) — where widget chats land.
* [Bot Journeys](bot-journeys.md) — per-widget journey assignment.
* [Contacts](../workspace/contacts.md) — pre-chat form fields seed new contacts.

<br />