Web widget

The web widget is the browser chat surface — a floating launcher (or an inline panel) that opens a live conversation. It is the reference implementation of the Lane.Chat visitor experience and the channel most integrations start with.

Install

One script tag:

<script
  src="https://cdn.lane.chat/js/widget.js"
  data-app-key="YOUR_APP_KEY"
></script>

See Installation for SPA manual init and inline mode, and the JavaScript API for controlling it from your code.

What it does

• Auto-mounts a launcher and opens a visitor session on first use.
• Streams messages in real time over WebSocket, with a REST fallback for history and sending.
• Renders rich messages — cards, carousels, buttons, forms, links, and markdown.
• Supports file uploads, typing indicators, visitor language selection, and (when enabled) voice/video/screen calls.
• Carries visitor identity and custom attributes from identify() into the agent panel.

Session lifecycle

1. The widget calls POST /v1/chat with your app_pub to create or resume a visitor session. The response carries a chatId, a visitor token (JWT), the authoritative visitor_uuid, and an appConfig block.
2. The widget opens a real-time connection with that token and registers the visitor.
3. Messages stream in real time; history and uploads use REST.

You rarely call these endpoints yourself for the web widget — the bundled script does it. They are documented under REST API for custom clients and the native SDKs.

Visitor identity

The widget maintains a dual-anchor identity: a stable visitor_uuid (client-generated, stored in localStorage and a cookie) plus a browser fingerprint. Both must match the same visitor record to count as a returning visitor. Push your own identity on top with identify().

Configuration

Appearance and behavior (welcome message, theme, position, auto-open, agent avatar, call toggles, knowledge-base search, and more) are configured per application in the dashboard and returned to the widget in the appConfig block on session init. Use updateTheme() to override theme config at runtime.