Chat Widget

The chat widget puts Lyro on your website as a floating bubble that opens into a chat panel. You install it with one script tag, then style its appearance and behavior from your dashboard - no code changes required for most settings.

Installing the widget

In your dashboard, open Distribution > Chat Widget and create a widget. Once it is saved, the Install tab gives you a one-line snippet. Paste it inside the <head> of every page where you want the widget to appear.

<script src="https://app.getlyro.ai/widget/YOUR-WIDGET-ID/widget.js" async></script>

The widget id is baked into the script URL, so the script reads it at runtime - the host page does not need to declare it anywhere. Each widget also has an Active / Disabled toggle (the Widget enabled switch on the Appearance tab). When disabled, the widget will not load on your site.

Tip: You can create multiple widgets and route each one to a different AI agent. Pick the agent under Behavior > Routing.

To learn how visitors and conversations flow into your dashboard, see Conversations and People.

Customization options

The widget editor is split into three tabs. Changes appear instantly in the live preview beside the form.

Appearance

Option	What it does
Accent color	The brand color used throughout the widget (defaults to a blue).
Avatar image	The image shown for the agent in the chat.
Banner image	A header image displayed at the top of the panel.

Content

Option	What it does
Title	The main greeting (for example, "Hi there!").
Subtitle	A short line under the title ("How can we help you?").
Welcome message	An optional first message shown when a chat opens.
Header title	Overrides the panel header text (defaults to the Title).
New chat title / subtitle	Copy shown on the start-a-new-chat screen.

You can also control the panel width in pixels (defaults to 420; ignored on mobile) and whether the panel is open by default when the page loads.

CSAT and idle follow-up

Under Behavior > Conversation lifecycle you can fine-tune how AI-handled chats close and get rated. These settings only affect AI-only chats - escalated conversations are left alone.

Auto-resolve idle chats marks a conversation as resolved after it has been quiet for a set number of minutes and the last reply came from the agent.
Ask AI-handled chats for a rating (CSAT) shows the visitor a 1-5 star panel when the conversation closes, either from the agent's natural end signal or the auto-resolve flip.
You can let the agent decide per turn when to end a chat with a rating prompt, and add optional workspace guidance for when it should fire.

Note: For team handoff behavior, see Escalation.

Debug toggles

Behavior > Developer view holds two toggles meant for testing, not production:

Show tool calls displays tool execution blocks (such as a knowledge search) inside chat messages.
Show reasoning displays the agent's "Thinking..." reasoning blocks.

Leave both off for live widgets so visitors only see clean replies.

JavaScript API

After the script loads, a global lyro(command, ...) function is available from anywhere on your page. Calls made before the script finishes loading are queued and replayed in order, so you can call it safely at any time.

Boot, update, and shutdown

The simplest way to pass visitor data is to set it before the script runs:

<script>
  window.lyroSettings = {
    name: "Jane Doe",
    user_id: "9876",            // your app's user id
    email: "[email protected]",
    plan: "pro"                 // any extra key becomes a contact property
  };
</script>
<script src="https://app.getlyro.ai/widget/YOUR-WIDGET-ID/widget.js" async></script>

You can also drive the lifecycle from code:

lyro('update', { plan: 'enterprise' });  // refresh properties when data changes
lyro('shutdown');                        // on logout: clears the visitor and unmounts the widget

Reserved identity keys (user_id, email) identify the visitor. Anything else at the top level is stored as a contact property and shown in People.

Identify and track

identify (via boot / update) attaches contact traits and merges anonymous and known visitors when you pass a user_id.
track records a time-stamped behavioral event on the contact, useful for automations and contact timelines.

lyro('track', 'plan_upgraded', { from: 'pro', to: 'enterprise' });

Pass a token for your own APIs

If your agent uses a custom tool that calls your backend, setAuthTokens hands it the visitor's own credential so the call runs as that visitor rather than as a shared service account:

lyro('setAuthTokens', { my_api: '<the visitor\'s access token>' });

Each entry becomes a {{auth_tokens.<name>}} value you can use anywhere in a custom tool - most often an Authorization header:

Authorization: Bearer {{auth_tokens.my_api}}

This is separate from identity. user_id and email tell Lyro who the visitor is; an auth token is a credential Lyro carries to your backend and never inspects. Lyro forwards it verbatim - it is never parsed, stored, or written to logs, and the tool request has redirects disabled so it cannot be replayed to another host.

A few things follow from that:

Supply it after every load. Tokens are kept in memory only, never in localStorage, so the widget has none until your page provides them. shutdown clears them.
Refresh it yourself. Lyro does not read the token, so it cannot tell when one expires. Call setAuthTokens again whenever you refresh the session, or the tool call fails partway through an answer.
Update one at a time. Names merge, latest wins, and passing an empty string removes that one entry.

lyro('setAuthTokens', { my_api: freshToken });  // replaces just this one
lyro('setAuthTokens', { my_api: '' });          // removes it

Tip: If the tool only needs to know who the visitor is rather than act on their behalf, use a signed identity token instead - see Visitor authentication. A token here is for calls your backend must authorize itself.

Add and remove tags

Use these for atomic updates to a visitor's tags so two parts of your UI can tag the same person without clobbering each other:

lyro('add_tags', ['vip', 'mailing_enabled']);
lyro('remove_tags', ['churned']);

Tip: Use add_tags / remove_tags for set-style edits, and update({ tags: [...] }) only when you mean to replace the whole list.

Link people for contact identification

When you pass a stable user_id (your app's own user id) alongside email, Lyro links the widget visitor to a single contact record. This merges anonymous browsing with the known account, so events tracked before sign-in bind to the contact once they identify. Render these values from your backend so each logged-in visitor gets the correct identity and properties.

To prove a visitor's identity rather than simply assert it, see Visitor authentication.

For programmatic identity, events, and other integration patterns, see API and developers and Tools and integrations.