Chat Widget: Integrate Your Agent into Web Application

Integrate your Flametree AI agent into any website with a powerful, customizable React chat widget. This widget provides seamless real-time chat functionality with extensive customization options and support for both floating and embedded deployment modes.

Prerequisites

Access to Flametree platform
A configured AI agent
Website with ability to edit HTML/add custom code
Basic understanding of HTML and JavaScript

Features

💬 Real-time messaging - Instant chat functionality
🎤 Audio recording - Voice message support with playback
🗣️ Speech-to-text - Convert voice to text automatically
🔊 Text-to-speech - Voice-over capabilities for accessibility
🎯 Flexible deployment - Floating button or embedded widget
📱 Responsive design - Optimized for all device sizes
⌨️ RTL support - Right-to-left text compatibility
🔄 Session management - Persistent conversation history
🎨 UI customization - Extensive styling options

The widget supports two deployment modes:

Mode	Description	Use Case
Floating	Displays as a floating button that opens a modal chat window	Customer support, help desk
Embedded	Occupies full width/height of parent container	Dedicated chat pages, integrated experiences

Integration Setup

Navigate to Your Agent
- Open the Flametree portal
- Go to the Agents section
- Click on the agent you want to configure
Locate the HTML Code Section
- On the right-hand configuration panel, scroll down to the HTML Code section
- Next to the HTML Code label, you'll see two icon buttons:
  - 👁 View — to preview the code
  - 📋 Copy — to copy the code to clipboard
Copy the Widget Code
- Click the Copy (📋) icon to copy the generated HTML snippet

Insert the Code
- Paste the copied snippet at the end of your page, just before the closing </body> tag
- For website builders (Tilda, Webflow, Wix, WordPress), paste into the custom HTML or script section
Alternative Manual Setup
- Add container element: <div id="chat-widget"></div>
- Include widget script: <script src="<PortalLink />/public-storage/widget/bot-chat-widget.umd.js"></script>
- Initialize widget with configuration
warning
If the widget is embedded, make sure to set a fixed height on the container element (for example, <div id="chat-widget" style="height: 600px">). Without it, the container will grow with each new message instead of scrolling, making the chat unusable

Make sure:

The code is placed before the closing </body> tag
The website allows external scripts
There are no JavaScript errors in the browser console

Step 3: Test the Integration

Reload Your Website
- The chat button should appear (floating mode) or widget should load (embedded mode)
Test Functionality
- Click the chat button or interact with embedded widget
- Send a test message to verify agent response
- Test voice features if enabled

If the widget does not respond, verify that:

the agent is active and not in error state
botRoute and authorizationToken are correct
the agent is properly configured

Configuration Options

Required Parameters

Parameter	Type	Description
`botRoute`	`string`	API endpoint URL for the chat bot
`authorizationToken`	`string`	Authorization token for API requests

Core Settings

Parameter	Type	Default	Description
`elementId`	`string`	`'chat-widget'`	HTML element ID for widget mounting
`userId`	`string`	`''`	Unique customer identifier
`userName`	`string`	`'Guest'`	Display name for the customer
`email`	`string`	`''`	Customer's email address
`phone`	`string`	`''`	Customer's phone number

tip

You can use multiple widgets on the same page by setting different elementId values

Appearance & Behavior

Parameter	Type	Default	Description
`isFloatingBtn`	`boolean`	`false`	Enable floating button mode
`primaryColor`	`string`	`#ff613e`	Primary theme color
`openByDefault`	`boolean`	`false`	Auto-open chat on load
`openByDefaultDelay`	`number`	`3000`	Delay in milliseconds for auto-open chat on load. Min value: 1000
`headerTitle`	`string`	`'Chat with the Agent'`	Chat header title
`headerTitleColor`	`string`	`'#000000'`	Header title color
`showPoweredBy`	`boolean`	`true`	Show Powered by footer
`showAiBotTimestamp`	`boolean`	`false`	Show response timestamps next to AI agent messages. By default, timestamps are automatically displayed only for customers and human operators (including copilot drafts).
`showAgentAvatar`	`boolean`	`false`	Show AI agent avatar icon next to its messages. Disabled by default for a cleaner UI.
`usePlainChat`	`boolean`	`true`	Enable ChatGPT-like plain text design for the chat widget without gray message bubbles. Enabled by default.
`showVoiceOver`	`boolean`	`false`	Displays the Voice over toggle in the widget. When `true`, customers can toggle automatic audio playback for all assistant messages. When `false`, the toggle is hidden, and audio playback is manual via the speaker icon under each message. 💡 Tip: to provide a standard GPT-like interaction pattern, keep this set to `false` (default). This hides the global automatic playback toggle, ensuring audio is only played when the customer explicitly clicks the speaker icon under a specific message.
`voiceOver`	`boolean`	`false`	Enable text-to-speech
`disableStreamingTts`	`boolean`	`false`	Controls how TTS audio is synthesized for bot replies. By default, the widget streams audio in chunks as the bot reply is being generated, so playback can start before the message is fully written. When `true`, this incremental synthesis is disabled — the full reply is synthesized in a single pass after the bot finishes typing, then played back as one audio segment. Useful when chunked synthesis produces audible seams or unnatural prosody, at the cost of a longer wait before audio starts. Has no effect unless the agent has text-to-speech enabled. 💡 Tip: enable this if you notice audible seams, clicks, or unnatural pauses between TTS chunks. Keep it `false` (default) when you want audio to start playing as early as possible — for example, in voice-first or hands-free scenarios where reducing perceived latency matters more than seamless prosody.
`timezone`	`string`	`''`	IANA timezone for message timestamps (for example, `'Europe/Madrid'`, `'America/New_York'`). Defaults to the browser's local timezone. ℹ️ Note: use this when the widget is embedded in an environment where the browser timezone may differ from the desired display timezone — for example, a kiosk, an internal tool with a fixed locale, or a server-side-rendered page.

Floating Button Customization

Parameter	Type	Default	Description
`floatingBtnSize`	`number`	`58`	Button size in pixels
`floatingBtnOpennedIconUrl`	`string`	`''`	Custom open icon URL
`floatingBtnClosedIconUrl`	`string`	`''`	Custom closed icon URL
`floatingBtnIconClosedSize`	`number`	`58`	Closed icon size
`floatingBtnIconOpenedSize`	`number`	`32`	Open icon size
`floatingBtnMarginBottom`	`number`	`8`	Bottom margin
`floatingBtnMarginRight`	`number`	`16`	Right margin
`floatingBtnMobileMarginBottom`	`number`	`8`	Mobile bottom margin
`floatingBtnMobileMarginRight`	`number`	`16`	Mobile right margin
`floatingBtnIconShape`	`circle, square`	`circle`	Shape variant of the default floating button icon
`floatingBtnIconBackgroundColor`	`string`	`#FB8535`	Background color of the default floating button icon
`floatingBtnClosedIconColor`	`string`	`#FFFFFF`	Inner icon stroke/fill color of the default floating button icon

Advanced Options

Parameter	Type	Default	Description
`disableSendingMessageWhileAwaitingResponse`	`boolean`	`false`	Prevent messages during bot response
`onError`	`(error: Error) => void`	–	Error handling callback
`avatarUrl`	`string`	`''`	Custom agent avatar URL
`tooltipText`	`string`	`''`	Floating button tooltip
`giftText`	`string`	`''`	Gift button text
`giftLink`	`string`	`''`	Gift button URL
`multiAgent`	`boolean`	`false`	Enable multi-agent support
`version`	`string`	`'v1'`	Widget version
`kwargs`	`object`	`'{}'`	Custom variables to pass when starting a session. Variables starting with `_` will not be logged or passed to the agent's prompt.
`messageListeners`	`Array<(message) => void>`	`undefined`	List of callbacks that track chat message events
`showStartNewSessionBtn`	`boolean`	`false`	Shows a button next to the chat input to start a new session. Hidden during audio recording

Start New Session Button

When showStartNewSessionBtn is set to true, a button appears to the right of the chat input. Selecting this button triggers the following sequence:

Sends a DELETE /session/{id} request to close the current session. Errors are ignored, and the restart proceeds.
Clears the message list immediately to display the typing indicator.
Skips the session history check and creates a new session directly.
Disables the button until the greeting from the new session arrives.

info

The button tooltip displays Start new conversation. While waiting for the new session to start, the button is visually disabled (opacity: 0.4) and non-interactive to prevent duplicate session creation.

Customer ID Management

The userId parameter follows this priority order:

Explicitly provided in widget parameters
Retrieved from localStorage (flametree-widget-userId-v2)
Auto-generated and saved to localStorage if not provided (when userId is empty)

Operation Modes

The widget supports three distinct operation modes

Mode 1: Standard Chat (version: 'v1')

Creates new session on initialization
No chat history retrieval
Simple, straightforward chat experience

Mode 2: Session Management (version: 'v2', multiAgent: false)

Retrieves all active customer sessions on initialization based on customer ID
Continues existing session if botRoute matches
Creates new session if no match found
No agent selection screen

Mode 3: Multi-Agent (version: 'v2', multiAgent: true)

Displays all active customer sessions
Shows agent selection screen
Allows switching between different agent conversations
Supports multiple sessions per agent

Implementation Examples

Basic Floating Chat

BotChatWidget.createBotChat({
  botRoute: 'https://api.example.com/bot',
  authorizationToken: 'your-auth-token',
  elementId: 'chat-widget',
  isFloatingBtn: true,
  primaryColor: '#007bff',
});

Embedded Chat with Voice Features

BotChatWidget.createBotChat({
  botRoute: 'https://api.example.com/bot',
  authorizationToken: 'your-auth-token',
  elementId: 'embedded-chat',
  isFloatingBtn: false,
  showVoiceOver: true,
  voiceOver: true,
  headerTitle: 'AI Assistant',
});

Advanced Multi-Agent Setup

BotChatWidget.createBotChat({
  // Required
  botRoute: 'https://api.example.com/bot',
  authorizationToken: 'your-auth-token',
  
  // Multi-agent configuration
  version: 'v2',
  multiAgent: true,
  
  // Customization
  elementId: 'chat-widget',
  userId: 'user123',
  userName: 'John Doe',
  email: 'john@example.com',
  isFloatingBtn: true,
  primaryColor: '#ff613e',
  openByDefault: false,

  // UI Customization
  headerTitle: 'Support Center',
  headerTitleColor: '#ffffff',
  showPoweredBy: false,
  avatarUrl: 'https://example.com/bot-avatar.png',
  showAiBotTimestamp: false, // Hidden by default for AI, but visible for humans
  
  // Floating button
  floatingBtnSize: 64,
  floatingBtnOpennedIconUrl: '',
  floatingBtnClosedIconUrl: '/icons/floating_icon_message.svg',
  tooltipText: 'Need help? Chat with us!',
  
  // Features
  showVoiceOver: true,
  voiceOver: true,
  disableSendingMessageWhileAwaitingResponse: true,
  
  // Gift feature
  giftText: 'Send Gift 🎁',
  giftLink: 'https://example.com/gifts',
  
  // Error handling
  onError: (error) => {
    console.error('Chat widget error:', error);
    // Custom error handling logic
  }
});

The widget exposes several optional helper methods that allow external scripts on your website to control the widget programmatically. These methods become available on the global window object after the widget is initialized.

Available Methods

// Open a specific session by ID (v2 mode)
window.BotChatWidget.openSession(sessionId: string): void;

// Programmatically open the chat widget
window.BotChatWidget.openChat(): void;

// Update session parameters for the currently active session.
// Example payload:
// {
//   env_info: {
//     _party_id: "123",
//     _session_id: "123",
//     customKey: "value",
//     ...
//   }
// }
window.BotChatWidget.updateSession(data: object): void;

// Action trigger for sending an optional message in a chat widget
window.BotChatWidget.runAction(message: string): void;

// Starts a new chat session in the widget
window.BotChatWidget.startNewSession(): void;

When to Use These Methods

Refreshing expiring tokens. Call updateSession() to pass updated session kwargs without restarting the session.
Deep-linking into conversations. Use openSession() to jump directly to a specific chat session.
Opening the widget from your UI. Attach openChat() to buttons, menus, or onboarding flows.
Sending an action message to the widget. Use runAction() to initiate an action message in the active chat session.
Starting a new conversation session. Use startNewSession() to create a new chat session in the widget.

The widget can receive custom messages from the agent over the WebSocket connection and use them to trigger JavaScript actions in the host application. When such a message arrives, the widget identifies the analytics provider, determines the event name, and invokes the appropriate client-side handler.

A custom message includes the analytics provider, the event name, and optional data. Based on this information, the widget identifies the provider, reads the event name, and runs the corresponding client-side action.

important

Custom WebSocket messages must include the field type: custom so the widget can distinguish them from system or internal messages.

A custom message uses the following format:

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

Parameter	Description
`type`	Must always be `custom` for custom event messages
`provider`	Target analytics provider, such as Google or Meta
`event`	Event name that the widget should trigger, for example `submitForm`
`data`	Object with arbitrary fields, for example submitted form data. May be empty

When the widget receives this message, it reads the type, provider and event name, then calls the matching client-side handler. For example, if the provider is Google Analytics, the widget adds a new entry to dataLayer.

Testing Your Integration

Verify Widget Appearance
- Check if floating button appears (floating mode)
- Verify embedded widget loads correctly (embedded mode)
Test Basic Functionality
- Click the chat button or interact with widget
- Send a test message like: Hello, what services do you offer?
- Verify the agent responds appropriately
Test Advanced Features
- Voice messages (if audio recording enabled)
- Text-to-speech playback (if voiceOver enabled)
- Multi-agent switching (if multiAgent enabled)
If voice features do not work, verify that:
- the browser supports audio recording
- microphone permissions are granted
- the website is served over HTTPS
- voice capabilities are enabled in the agent

Browser Storage

`localStorage`

Key	Purpose
`flametree-widget-userId-v2`	Auto-generated user ID when not explicitly provided
`unreadConversations`	Array of unread conversation IDs

`sessionStorage`

Key	Purpose
`flametree-widget-defaultAuthorizationToken`	Initial authorization token
`flametree-widget-authorizationToken`	Current active token (updated in multi-agent mode)
`flametree-widget-defaultBotRoute`	Initial bot route URL
`${botRoute}-sessionId`	Active session ID for specific agent

Browser Support

The Flametree Chat Widget is compatible with all modern browsers that support:

ES6+ JavaScript features
MediaRecorder API (for audio recording)
Local/Session Storage
CSS Grid and Flexbox

Supported Browsers:

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

Security Considerations

Protect authorization tokens. Do not expose them in client-side code or public repositories
Rotate tokens if they are compromised
Monitor widget usage for suspicious activity
Handle customer data according to your privacy policy and applicable regulations
Obtain customer consent before enabling voice recording

Chat Widget: Integrate Your Agent into Web Application

Prerequisites

Features

Widget Types

Integration Setup

Step 1: Get the Widget Code

Step 2: Add Widget to Your Website

Step 3: Test the Integration

Configuration Options

Required Parameters

Core Settings

Appearance & Behavior

Floating Button Customization

Advanced Options

Start New Session Button

Customer ID Management

Operation Modes

Mode 1: Standard Chat (version: 'v1')

Mode 2: Session Management (version: 'v2', multiAgent: false)

Mode 3: Multi-Agent (version: 'v2', multiAgent: true)

Implementation Examples

Basic Floating Chat

Embedded Chat with Voice Features

Advanced Multi-Agent Setup

External Widget Methods

Widget Message Handling (Custom Events from Agent)

Testing Your Integration

Browser Storage

`localStorage`

`sessionStorage`

Browser Support

Security Considerations

Was this article helpful?

Prerequisites​

Features​

Widget Types​

Integration Setup​

Step 1: Get the Widget Code​

Step 2: Add Widget to Your Website​

Step 3: Test the Integration​

Configuration Options​

Required Parameters​

Core Settings​

Appearance & Behavior​

Floating Button Customization​

Advanced Options​

Start New Session Button​

Customer ID Management​

Operation Modes​

Mode 1: Standard Chat (version: 'v1')​

Mode 2: Session Management (version: 'v2', multiAgent: false)​

Mode 3: Multi-Agent (version: 'v2', multiAgent: true)​

Implementation Examples​

Basic Floating Chat​

Embedded Chat with Voice Features​

Advanced Multi-Agent Setup​

External Widget Methods​

Widget Message Handling (Custom Events from Agent)​

Testing Your Integration​

Browser Storage​

localStorage​

sessionStorage​

Browser Support​

Security Considerations​

Related Resources​

Was this article helpful?

Prerequisites

Features

Widget Types

Integration Setup

Step 1: Get the Widget Code

Step 2: Add Widget to Your Website

Step 3: Test the Integration

Configuration Options

Required Parameters

Core Settings

Appearance & Behavior

Floating Button Customization

Advanced Options

Start New Session Button

Customer ID Management

Operation Modes

Mode 1: Standard Chat (version: 'v1')

Mode 2: Session Management (version: 'v2', multiAgent: false)

Mode 3: Multi-Agent (version: 'v2', multiAgent: true)

Implementation Examples

Basic Floating Chat

Embedded Chat with Voice Features

Advanced Multi-Agent Setup

External Widget Methods

Widget Message Handling (Custom Events from Agent)

Testing Your Integration

Browser Storage

`localStorage`

`sessionStorage`

Browser Support

Security Considerations

Related Resources