Web Widget

The Web Widget embeds a Flametree agent into any website as a chat window, with real-time messaging, voice input and playback, file attachments, and configurable appearance.

Where the widget is configured

The Web Widget is documented here under Settings > Channels so you can find it next to the other channels, but it is not created on that screen. You enable the widget, set its appearance, and copy the embed code on the agent's page — there are no external credentials to manage.

Before you start

• A configured agent in the AI Agents section.
• Access to edit your website's HTML (or the custom-code block of your website builder).

Get the embed code

The embed code is generated per agent on the agent's page.

1. Open AI Agents and select your agent.
2. Find the Web widget section and switch it on.
3. Configure the built-in options: Display name, Show floating chat button, Primary color, Voice over, Tooltip text, Allow voice messages, the floating button icon (Choose an existing icon or Create a custom icon, with Button color and Icon color), and Floating button size.
4. Click Apply (or save the agent).
5. In the Html code controls, click the view icon to preview the Widget Html code, or use the copy icon / Copy HTML code to copy the snippet.

Try it before embedding

Click Open demo page next to the Html code controls to test the widget on a hosted demo page — no changes to your site required.

Add the widget to your site

1. Paste the copied snippet immediately before the closing </body> tag of your page.
2. For website builders (Tilda, Webflow, Wix, WordPress), paste it into the custom HTML/script block instead.
3. Reload the page. The floating button or embedded chat should appear.

The snippet contains a container element, the widget script, and an initialization call:

<div id="chat-widget"></div>
<script src="https://<your-portal-host>/public-storage/widget/bot-chat-widget.umd.js"></script>
<script>
  BotChatWidget.createBotChat({
    botRoute: 'https://<your-portal-host>/<agent-route>',
    authorizationToken: '<token>',
    elementId: 'chat-widget',
    isFloatingBtn: true,
    version: 'v2',
  });
</script>

Embedded mode needs a fixed height

If isFloatingBtn is false, set a fixed height on the container, for example <div id="chat-widget" style="height: 600px"></div>. Without it the container grows with each message instead of scrolling.

Choose floating or embedded mode

Mode	Setting	Use case
Floating	isFloatingBtn: true	A button in the page corner that opens a chat window on top of the page. Typical for support and helpdesk.
Embedded	isFloatingBtn: false (default)	The chat fills the container element. Typical for dedicated chat pages.

Configuration options

All options below are passed as properties of the object given to BotChatWidget.createBotChat({ ... }). The generated snippet already contains the required ones; add the rest as needed.

Required parameters

Parameter	Type	Description
botRoute	string	The agent's endpoint URL. Taken from the generated snippet.
authorizationToken	string	The agent's widget token. Taken from the generated snippet.

Core settings

Parameter	Type	Default	Description
elementId	string	'chat-widget'	ID of the container element. Use different IDs to place several widgets on one page.
isFloatingBtn	boolean	false	Floating button (true) or embedded (false).
version	'v1' | 'v2'	–	Operation mode. See Operation modes.
multiAgent	boolean	false	Multi-agent mode for v2. Ignored on v1.
timezone	string	browser timezone	IANA timezone for timestamps, for example 'Europe/Madrid'.

Appearance and behavior

Parameter	Type	Default	Description
theme	'light' | 'dark'	'light'	Widget color theme.
primaryColor	string	–	Primary accent color (hex).
headerTitle	string	'Chat with the Agent'	Header title text.
headerTitleColor	string	–	Header title color.
showHeader	boolean	–	Show or hide the chat header in embedded mode.
avatarUrl	string	''	URL of a custom agent avatar image.
showAgentAvatar	boolean	false	Show the agent avatar next to its messages.
showAiBotTimestamp	boolean	false	Show timestamps on AI messages. Timestamps are always shown for customer and human-operator messages.
usePlainChat	boolean	true	Plain, bubble-less message design.
reactions	boolean	true	Thumbs up/down reactions on agent messages.
showPoweredBy	boolean	true	"Powered by" footer. The portal-generated snippet sets this to false.
forceMobileLayout	boolean	–	Force the mobile layout regardless of screen size.
flametreeIconVariant	'static' | 'animated'	–	Variant of the default widget icon.

Floating button

These options apply only when isFloatingBtn is true.

Parameter	Type	Default	Description
floatingBtnSize	number	58	Button size in pixels.
floatingBtnMobileSize	number	58	Button size on mobile.
floatingBtnIconShape	'circle' | 'square'	'circle'	Shape of the default icon.
floatingBtnIconBackgroundColor	string	–	Background color of the default icon.
floatingBtnClosedIconColor	string	–	Stroke/fill color of the default icon.
floatingBtnClosedIconUrl	string	''	Custom icon image URL for the closed state.
floatingBtnOpennedIconUrl	string	''	Custom icon image URL for the open state.
floatingBtnIconClosedSize	number	32	Closed-state icon size.
floatingBtnIconOpenedSize	number	32	Open-state icon size.
floatingBtnMarginBottom	number	8	Offset from the bottom edge of the page.
floatingBtnMarginRight	number	16	Offset from the right edge of the page.
floatingBtnMobileMarginBottom	number	8	Offset from the bottom edge on mobile.
floatingBtnMobileMarginRight	number	16	Offset from the right edge on mobile.
tooltipText	string	''	Tooltip text shown next to the button.
openByDefault	boolean	false	Auto-open the chat on page load.
openByDefaultDelay	number	3000	Delay before auto-open, in milliseconds. Minimum 1000.

Voice playback

Parameter	Type	Default	Description
voiceOver	boolean	false	Enable text-to-speech for agent replies.
showVoiceOver	boolean	false	Show the Voice over toggle in the widget. Keep false if you prefer manual playback with the speaker icon on each message.
disableStreamingTts	boolean	false	Synthesize the full reply in one pass instead of streaming chunks. Enable if you hear audible seams between chunks.

Voice message recording is enabled with the Allow voice messages setting on the agent page, not a widget parameter.

Advanced

Parameter	Type	Default	Description
kwargs	object	–	Custom variables passed when a session starts. Keys that start with _ are not logged and are not passed into the agent's prompt — use the underscore prefix for tokens and other secrets.
showStartNewSessionBtn	boolean	false	Show a Start new conversation button next to the input. It closes the current session and starts a fresh one.
disableSendingMessageWhileAwaitingResponse	boolean	false	Block the input while the agent is composing a reply.
messageListeners	array	–	Callbacks that observe chat message events.
onError	(error) => void	–	Error callback.

Example configurations

A branded floating support button:

<div id="chat-widget"></div>
<script src="https://<your-portal-host>/public-storage/widget/bot-chat-widget.umd.js"></script>
<script>
  BotChatWidget.createBotChat({
    botRoute: 'https://<your-portal-host>/<agent-route>',
    authorizationToken: '<token>',
    elementId: 'chat-widget',
    version: 'v2',
    isFloatingBtn: true,
    primaryColor: '#0a7d4f',
    headerTitle: 'Support',
    tooltipText: 'Questions? Chat with us',
    floatingBtnSize: 64,
    openByDefault: true,
    openByDefaultDelay: 5000,
  });
</script>

An embedded chat on a dedicated page, tied to the logged-in customer:

<div id="chat-widget" style="height: 600px"></div>
<script src="https://<your-portal-host>/public-storage/widget/bot-chat-widget.umd.js"></script>
<script>
  BotChatWidget.createBotChat({
    botRoute: 'https://<your-portal-host>/<agent-route>',
    authorizationToken: '<token>',
    elementId: 'chat-widget',
    version: 'v2',
    isFloatingBtn: false,
    theme: 'dark',
    userId: 'customer-12345',
    userName: 'Maria Lopez',
    email: 'maria@example.com',
    kwargs: {
      plan: 'pro',
      _authToken: '<session-token>',
    },
  });
</script>

Customer context and user identity

Pass customer details at initialization so sessions are tied to a known person:

Parameter	Type	Default	Description
userId	string	''	Customer identifier from your system.
userName	string	''	Customer display name.
email	string	''	Customer email.
phone	string	''	Customer phone number.
tenantId	string	–	Tenant identifier for multi-tenant installations.

How userId is resolved:

• If you pass a userId (for example, the logged-in user's ID from your backend), the widget uses it. In v2 mode this is what lets a customer continue earlier sessions across visits and devices.
• If userId is empty, the widget generates an anonymous ID and stores it in the browser's localStorage under the key flametree-widget-userId-v2. The same browser keeps the same identity; clearing site data resets it.

To pass additional context (plan, page URL, cart contents), use kwargs — see Advanced.

Operation modes

Mode	Settings	Behavior
Standard	version: 'v1'	A new session on every page load; no history retrieval.
Session management	version: 'v2', multiAgent: false	The widget looks up the customer's active sessions by userId and continues the matching one; otherwise it creates a new session.
Multi-agent	version: 'v2', multiAgent: true	Shows all of the customer's active sessions and an agent selection screen; the customer can switch between agents.

multiAgent has no effect on v1.

Control the widget from your page

After initialization, control methods are available on window.BotChatWidget. The controller object returned by createBotChat exposes the same methods plus a ready promise you can await before calling them.

window.BotChatWidget.openChat();
window.BotChatWidget.openSession(sessionId);
window.BotChatWidget.updateSession({ env_info: { customKey: 'value' } });
window.BotChatWidget.runAction('text');
window.BotChatWidget.startNewSession();

To call a method as soon as the widget is ready, await the ready promise first:

const widget = BotChatWidget.createBotChat({
  /* ...options... */
});

document.querySelector('#contact-us').addEventListener('click', async () => {
  await widget.ready;
  widget.openChat();
});

Method	When to use
openChat()	Open the chat window from your own UI — a "Chat with us" button, an onboarding step, an exit-intent prompt. Use this instead of simulating clicks on the floating button.
openSession(sessionId)	Jump to a specific session (v2 modes).
updateSession({ env_info: { ... } })	Update the running session's custom variables — for example, refresh an auth token you originally passed in kwargs.
runAction('text')	Send an action message into the chat on the customer's behalf, for example to start a specific scenario when they click a page element.
startNewSession()	Close the current session and start a fresh one, for example after the customer logs out.

Receive custom events from the agent

The agent can push events to the host page over the widget's WebSocket connection — useful for firing conversion or analytics events in tools such as Google Analytics or Meta when the conversation reaches a milestone. The agent sends a message of this shape:

{ "type": "custom", "provider": "string", "event": "string", "data": {} }

• provider selects the client-side handler. For Google, the widget pushes the event to the page's dataLayer, where Google Tag Manager and Google Analytics pick it up.
• event is the event name; data carries optional payload fields.

For example, an agent could send the following when a visitor leaves their contact details:

{
  "type": "custom",
  "provider": "Google",
  "event": "lead_captured",
  "data": { "plan": "pro" }
}

To observe raw chat message events yourself, pass callbacks in the messageListeners option.

Test the integration

1. Click Open demo page on the agent page and verify the widget looks and behaves as expected.
2. Reload your own site and check that the floating button or embedded chat appears.
3. Send a test message and verify the agent responds.
4. If you pass userId, reload the page in v2 mode and confirm the conversation continues instead of starting over.

Common issues

• The widget does not appear — check the browser console for script errors and confirm the container element ID matches elementId.
• The widget appears but the agent never replies — confirm the agent is running and that botRoute and authorizationToken match the snippet generated for this agent. Re-copy the snippet if in doubt.
• The embedded widget keeps growing taller — set a fixed height on the container element (see the warning above).
• Voice input or playback fails — the site must be served over HTTPS, the browser must have microphone permission, and speech-to-text must be configured on the agent.
• Sessions do not continue across visits — use version: 'v2' and pass a stable userId; anonymous identities are stored per browser and reset when site data is cleared.

Related pages

• Channels overview
• AI Agents
• Sessions