The chat widget

The widget is a single script that renders a chat launcher on any website and connects it to an app.

Install

Copy the snippet from App → Install. It looks like this:

<script src="https://<widget host>/widget.js"
        data-app-id="app_xxxxxxxxxxxxxxxxxxxxxxxx"
        data-api-url="https://<api host>/api"
        async></script>

data-app-id is the app's public id; data-api-url is the AgentRow API base URL. Optional attributes: data-identity-token (a JWT already available at page load) and data-open="true" to open the panel immediately.

Signing users in

Call AgentRow.identify(token) after your user logs in, with a JWT your backend signs using the app secret. Under "require verified" enforcement the widget shows a sign-in gate until it is called. Call AgentRow.logout() when the user signs out.

JavaScript API

AgentRow.init(options) starts the widget with options such as appId, apiUrl, identityToken, autoOpen, container (mount inline in an element), mode (floating or inline), theme, css, renderers, strings, showToolActivity and showConversations.

Methods: identify, logout, open, close, send(text), newConversation, openConversation(id), listConversations, showConversations, on, once, off, waitFor(event, options), getClient (headless client), destroy, createClient (build your own UI on the client), and version.

Events

The widget emits events your page can react to: ready, open, close, session:started, session:ended, identity:required, conversations:loaded, conversation:loaded, conversation:opened, conversation:new, conversation:created, message:sent, message:failed, message:delta (streamed text), message:received, run:queued, run:started, run:completed, run:failed, tool:started, tool:delta, tool:completed, tool:failed, stream:state and error. Handlers can filter by tool name, so a page can react when a specific tool completes, for example to refresh an order panel after the assistant looked it up.

Customisation

• From the dashboard (no redeploy): placeholder, welcome message, suggested prompts, accent colour, light or dark theme, position, launcher label, branding, and whether built-in tool activity is shown.
• From the page: theme tokens (colours, radius, panel width), extra CSS inside the widget, host CSS through shadow parts (launcher, panel, header, messages, composer, footer), custom renderers for messages and other parts, custom copy for every string, inline mounting, and a headless client for a fully custom UI.
• Tool activity: per tool, choose whether end users see nothing, a status line ("Looking up your order…") or full detail. Built-in tools follow the app-level setting.

Conversations in the widget

End users see their conversation list, can start a new conversation and switch between earlier ones. Conversations are tied to the end user, so a signed-in user sees the same history on every device; an anonymous visitor's history stays with their browser until they sign in and it is merged.