Widget configuration

This is the developer reference for the embeddable chat widget. It lists every initialization parameter, the methods you can call to control the widget from your page, the custom events the agent can push to your page, and the browser storage keys the widget uses.

For the task of switching the widget on, configuring its appearance, and embedding it on your site, see Web Widget. The parameters below are passed as properties of the object you give 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'.

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

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. The same browser keeps the same identity; clearing site data resets it. See Browser storage keys.

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.

Sessions and input

Parameter	Type	Default	Description
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.
onError	(error) => void	–	Error callback.
messageListeners	array	–	Callbacks that observe chat message events. See Message listeners.

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 methods

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();

Method	Signature	When to use
openChat()	openChat(): void	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)	openSession(sessionId: string): void	Jump to a specific session (v2 modes).
updateSession(data)	updateSession({ env_info: { ... } }): void	Update the running session's custom variables — for example, refresh an auth token you originally passed in kwargs.
runAction(text)	runAction(text: string): void	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()	startNewSession(): void	Close the current session and start a fresh one, for example after the customer logs out.

The ready promise

To call a method as soon as the widget is ready, await the ready promise on the controller returned by createBotChat.

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

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

Custom events

The agent can push events to the host page over the widget's WebSocket connection — useful for firing conversion or analytics events 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.
• event is the event name; data carries optional payload fields.

The widget ships handlers for two providers:

provider	Where the event goes
Google	Pushed to the page's dataLayer, where Google Tag Manager and Google Analytics pick it up.
Meta	Sent to the Meta Pixel as a custom event (fbq('trackCustom', ...)), when the pixel is present on the page.

Events with any other provider value are ignored.

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" }
}

Message listeners

To observe raw chat message events yourself, pass an array of callbacks in the messageListeners option. Each callback receives one chat message object as it is added to the conversation.

BotChatWidget.createBotChat({
  /* ...options... */
  messageListeners: [
    (message) => {
      console.log('chat message', message);
    },
  ],
});

Browser storage keys

The widget stores a small amount of state in the browser. Clearing site data resets all of it.

Key	Storage	Purpose
flametree-widget-userId-v2	localStorage	Anonymous customer ID, generated when no userId is passed (v2). The same browser keeps the same identity.
unreadConversations	localStorage	Array of unread conversation IDs.
${botRoute}-sessionId	sessionStorage	The current session ID for this tab, used to resume the session on reload.

Related pages

• Web Widget — switch on, configure, and embed the widget
• Channels — create, manage, and attach connections
• Sessions — every conversation, whatever its channel