Flametree 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 AI 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="https://portal.flametree.ai/public-storage/widget/bot-chat-widget.umd.js"></script>
- Initialize widget with configuration

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

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 user identifier
`userName`	`string`	`'Guest'`	Display name for the user
`email`	`string`	`''`	User's email address
`phone`	`string`	`''`	User's phone number

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
`showWaitingMessage`	`boolean`	`false`	Show typing indicators
`voiceOver`	`boolean`	`false`	Enable text-to-speech

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
`flametreeIconVariant`	`static, animated`	`static`	Widget icon display option: static or animated image

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.

User 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 user sessions on initialization
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 user 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,
  voiceOver: true,
  showWaitingMessage: 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',
  
  // Floating button
  floatingBtnSize: 64,
  floatingBtnOpennedIconUrl: './assets/close-icon.svg',
  floatingBtnClosedIconUrl: './assets/chat-icon.svg',
  tooltipText: 'Need help? Chat with us!',
  
  // Features
  voiceOver: true,
  showWaitingMessage: 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;

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.

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

type — must always be custom for custom event messages
provider — the target analytics provider, such as Google or Meta
event — the event name that the widget should trigger. For example, submitForm
data — an object with arbitrary fields. Fox 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

Quick Test Steps

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)

Common Issues & Solutions

Widget not appearing

Possible causes:

HTML code placed incorrectly
JavaScript errors blocking execution
Website security policies blocking external scripts

Solutions:

Check placement: Ensure code is in <head> or before closing </body> tag
Console errors: Check browser console for JavaScript errors
Script permissions: Verify website allows external scripts
Cache issues: Clear browser cache and reload

Widget not responding

Possible causes:

Agent is in "Error" status
Invalid botRoute or authorizationToken
Network connectivity issues
Missing agent workflow configuration

Solutions:

Check agent status: Confirm agent is running and not in error state
Verify credentials: Check botRoute and authorizationToken are correct
Network test: Verify connectivity to Flametree servers
Agent config: Ensure agent has proper workflow configuration

Voice features not working

Possible causes:

Browser doesn't support MediaRecorder API
Microphone permissions denied
Voice features not enabled in agent

Solutions:

Browser support: Use Chrome 60+, Firefox 55+, Safari 12+, or Edge 79+
Permissions: Allow microphone access when prompted
Agent settings: Enable voice features in agent configuration
HTTPS required: Voice features require secure (HTTPS) connection

Styling conflicts

Possible causes:

CSS conflicts with existing website styles
Z-index issues with floating button
Responsive design problems

Solutions:

CSS isolation: Use more specific selectors or !important declarations
Z-index: Adjust floating button z-index values
Responsive testing: Test on different screen sizes
Custom styling: Override default styles with custom CSS

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+

FAQ

Can I customize the widget appearance?

Yes, the widget offers extensive customization options including:

Primary colors and themes
Custom icons for floating button
Header titles and colors
Button sizes and positioning
Custom avatars and branding

Does the widget work on mobile devices?

Yes, the widget is fully responsive and optimized for mobile devices. It includes specific mobile margin settings and touch-friendly interactions.

Can I use multiple widgets on the same page?

Yes, you can embed multiple widgets by using different elementId values for each widget instance.

Is the chat history persistent?

Yes, when using version 'v2', the widget supports session management and can retrieve previous conversations based on user ID.

How do I handle widget errors?

Use the onError callback parameter to implement custom error handling:

onError: (error) => {
  console.error('Widget error:', error);
  // Your custom error handling logic
}

Flametree 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

User 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

Quick Test Steps

Common Issues & Solutions

Browser Storage

localStorage

sessionStorage

Browser Support

FAQ

Security Considerations

Token Security

Privacy Settings

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​

User 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​

Quick Test Steps​

Common Issues & Solutions​

Browser Storage​

localStorage​

sessionStorage​

Browser Support​

FAQ​

Security Considerations​

Token Security​

Privacy Settings​

Related Resources​

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

User 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

Quick Test Steps

Common Issues & Solutions

Browser Storage

localStorage

sessionStorage

Browser Support

FAQ

Security Considerations

Token Security

Privacy Settings

Related Resources