Chatflow Widget Documentation
This document outlines the public methods available in the Chatflow widget JavaScript API, providing developers with the ability to interact with and control the Chatflow widget programmatically.
Getting Started
This document outlines the public methods available in the Chatflow widget JavaScript API, providing developers with the ability to interact with and control the Chatflow widget programmatically.
Terminology
- LLM
- LLM Stands for Large Language Model, a type of AI model that can generate human-like text based on the input it receives, this is what powers the core of ChatFlow's chatbot functionality.
- Tone (ChatFlow Personality)
- The "Tone" you select for your ChatFlow chatbot, this will determine the "personality" of the chatbot, and how it interacts with users (if it makes jokes, encurages the user, or just responds with the information asked for and nothing else.
Chatflow has 5 tones available: "Professional", "Friendly", "Funny", "Neutral" and "Assertive"
- Friendly Offers a warm and welcoming interaction.
- Professional Maintains a formal, business-like demeanor.
- Humorous Incorporates light-hearted humor into responses.
- Calm Provides responses in a soothing and serene manner.
- Neutral Does not exhibit any particular tone.
- Assertive Offers clear, confident, and decisive responses, conveying authority without aggression.
- Chatflow
- The Chatflow widget is a chatbot platform that allows you to create and deploy interactive chatbots on your website.
- Widget
- The Chatflow widget is a JavaScript-based chatbot widget that can be embedded on your website to provide chatbot functionality to your users.
- Chatbot
- A chatbot is an AI-powered conversational agent that can interact with users in natural language.
- Chat Session
- A chat session is a conversation between a user and a chatbot, typically initiated by the user interacting with the chat widget on your website.
- Chat Message
- A chat message is a message sent by the user or the chatbot during a chat session.
- Quick Prompt
- A pre-defined question or a link that will be displayed as a grid of button at the start of a chat session, Questions will "send" a message to the chatbot and the chatbot will respond, while a link, will open a new page.
- Chatflow Dashboard
- The Chatflow dashboard is a web-based interface that allows you to create, manage, and analyze chatbots and chat sessions.
- Chatflow JavaScript API
- The Chatflow API is a set of public methods and events that allow you to interact with and control the Chatflow widget programmatically.
- Visitor
- A visitor is a user who interacts with the Chatflow widget on your website, a visitor can be identified using the `identify` method, and is tied to a chat session in the Chatflow dashboard.
- ChatFlow Visitor Cookie
- A cookie that is set in the visitor's browser and passed along to the chatflow server to identify the visitor and their chat session, it has an expiration date of 10 days by default, but can be changed with the `data-cookie-duration` attribute.
Initialization
The widget initializes automatically when the DOM content is fully loaded, requiring no manual initiation from the developer's side.
Most configurations can be set using data-*
attributes on the widget's iframe snippet, this will override the
configuration set in the Chatflow dashboard.
Configuration
Available options for the widget can be set using data-*
attributes on the widget's iframe snippet.
Attribute Name | Default | Description |
---|---|---|
data-chatbot-id |
(required) | The unique identifier for the chatbot |
data-init |
true |
Whether the widget should be initialized automatically. Set to false to initialize manually. |
data-open |
false |
Whether the widget should be open by default. |
data-open-delay |
0 |
The delay in milliseconds before the widget is opened when data-open is set tot true , useful for showing the widget after a certain amount of time, has no effect if data-open is set to false . |
data-position |
right |
The initial position of the widget, can be left or right . |
data-dark-mode |
false |
Whether the widget should use dark mode. |
data-trigger-color |
#3b82f6 |
The color of the widget's trigger button, By default, it uses standard "corporate blue". |
data-trigger-text-color |
#ffffff |
The text color of the widget's trigger button, By default, it uses white. |
data-initial-size |
maximized |
The initial size of the widget, can be maximized , minimized , or halfed . |
data-btn-open-text |
Open |
The text to display on the widget's open button. |
data-btn-close-text |
Close |
The text to display on the widget's close button. |
data-hide-toggle-button |
false |
Whether to hide the toggle button, set this to true if you want to control the widget manually. |
data-close-on-session-end |
false |
Whether the widget should close when the chat session ends. |
data-mobile-force-maximize |
false |
If set to true , the widget will always be maximized (full-screen) on mobile devices (using 768px as the breakpoint), if set to false , the widget will adjust to the screen size. |
data-cookie-duration |
10 |
The expiration time in days for the ChatFlow visitor cookie. |
data-widget-half-height |
26rem |
The height of the widget when size is set to half (see), can be any valid CSS height value (px , rem , em , % , etc, see MDN for a complete list, We recommend using a value no smaller than 26rem (approx 416px) to ensure the chatbot is usable) |
data-widget-height |
46rem |
The height of the widget when size is set to minimized (the default size) (see), can be any valid CSS height value, same as above, We recommend using a value no smaller than 46rem (approx 736px) to ensure the message history doesn't get cut off, or requires excessive scrolling. |
data-widget-width |
28rem |
The width of the widget, can be any valid CSS width value, same as above. We recommend using a value around 28rem (approx 450-500px) to ensure the message history doesn't get squished, causing readability issues, on mobile, the widget will automatically adjust to the screen size, unless data-mobile-force-maximize is set to false . |
data-widget-button-spacing |
10px |
The spacing between the widget and the default toggle button |
data-widget-horizontal-offset |
10px |
The horizontal offset of the widget from the edge of the screen. (left / right) |
data-widget-top-offset |
10px |
The space between the edge of the screen and top of the widget, useful if you have a "sticky header" or other fixed element towards the top of the screen, that you don't want the widget to overlap or go "underneath". |
data-widget-bottom-offset |
10px |
The space between the edge of the screen and bottom of the widget, Particularly useful if you want to make room for a custom toggle button or other elements that you don't want the widget to overlap with (eg. a "back to top" button, newsletter signup, or cookie consent banner). |
Manual Initialization
However, if you need to initialize the widget manually, you need to modify the iframe snippet to include the
data-init="false"
attribute. This will prevent the widget from initializing automatically, allowing you to initialize
it manually using the initialize
method.
Example:
Please note that the data-init
attribute is set to false
to prevent the widget from initializing automatically.
<script
id="chatflow-widget"
data-open="true"
data-dark-mode="false"
data-chatbot-id="your-chatbot-id"
data-trigger-color="#000000"
data-trigger-text-color="#ffffff"
data-btn-open-text="Open"
data-btn-close-text="Close"
data-init="false"
src="https://chatflow.no/embed.js"
></script>
Then, you can initialize the widget manually using the initialize
method.
// Initialize the widget manually
document.addEventListener("DOMContentLoaded", function () {
Chatflow.initialize();
});
Usage with Laravel Livewire wire:navigate
feature
When using wire:navigate
to navigate between pages in
a Laravel Livewire application, you should
modify your code to this instead:
document.addEventListener("livewire:navigated", () => {
Chatflow.initialize();
});
Methods
The Chatflow widget JavaScript API provides a set of methods for interacting with the widget programmatically.
emit(eventName)
Description:
Emits a custom event with the specified name.
Parameters:
-
eventName
(string): The name of the event to emit.
Usage:
Chatflow.emit("trigger-analytics", {
meta: "some data",
timestamp: "2024-02-25T12:00:00Z",
});
on(eventName, handler)
Description:
Allows adding event listeners for custom Chatflow events.
Parameters:
-
eventName
(string): The name of the event to listen for. -
handler
(function): The function to execute when the event is triggered.
Usage:
// Custom User-Defined Event
Chatflow.on("trigger-analytics", function (event) {
// Example: Send event to analytics
ga(
"send",
"event",
"Chatflow",
"Custom event triggered",
event.detail.meta,
);
});
// Built-in Chatflow Event
Chatflow.on("message:sent", function (event) {
console.log("sent message to chatbot", event.detail);
});
toggleWidget()
Description:
Toggles the widget's visibility between open and closed states.
- When the widget is closed, it will open, and when the widget is open, it will close.
- When closed, the iframe is
display: none
, and when open, the iframe isdisplay: block
. - When closed, the button is set to
display: block
, and when open, the button is set todisplay: none
. - When the widget is opened, the
opened
event is triggered, and when the widget is closed, theclosed
event is triggered.
Usage:
Chatflow.toggleWidget();
open()
Description:
Opens the widget, see toggleWidget
for more details.
Usage:
Chatflow.open();
close()
Description:
Closes the widget, see toggleWidget
for more details.
Usage:
Chatflow.close();
endChatSession()
Description:
Ends the current chat session, closing the chat session will set the end date for the conversations in the ChatFlow dashboard and prevent further messages from being tied to the Chat session.
Any new messages sent after the chat session has ended will start a new chat session.
If the data-close-on-session-end
attribute is set to true
, the widget will close after the chat session has ended,
this can be useful for chatbots that are used for support or sales, where the chat session is expected to end after the
user has received the information they need.
Usage:
Chatflow.endChatSession();
maximizeWidget()
Description:
Resize the chat widget to cover the full screen, on mobile devices, this will happen automatically, if you don't want
this behavior, you can set the data-mobile-force-maximize
attribute to false
on the iframe snippet.
Usage:
Chatflow.maximizeWidget();
halfWidget()
Description:
Sets the widget to half of its maximum height, useful for when you want to keep the chat widget available for questions or comments, without taking up too much space on the screen.
Usage:
Chatflow.halfWidget();
minimizeWidget()
Description:
Minimizes the widget to its default size.
Usage:
Chatflow.minimizeWidget();
cycleSize()
Description:
Cycles through the available sizes for the widget, the cycle order is minimized
-> maximized
-> halfed
, then it
repeats.
Usage:
Chatflow.cycleSize();
changeSize(newSize)
Description:
Changes the size of the widget to the specified size.
Parameters:
-
newSize
(string): The new size for the widget, can beminimized
,maximized
, orhalf
.
Usage:
Chatflow.changeSize("maximized");
setInput()
Description:
Sets the input field to the specified message, useful for pre-filling the input field with a message or response.
Parameters:
-
text
(string): The message to set in the input field.
Usage:
Chatflow.setInput("Hey, tell me a joke about ...");
send()
Description:
Sends a message from the user to the Chatbot programmatically, the sent message will be visible in the chat history, useful to start a chat session when a user clicks a button or interacts with a form on your website.
This is particularly powerful when paired with identify()
to let the chatbot know the user's name and (optionally)
email.
identify(userInfo)
Description:
Identifies the user in the chat session, typically used for pre-filling the user's name and email in the chat widget when the user is already logged in to your website, or you have previously collected this information.
Parameters:
-
userInfo
(Object): An object containing user information.-
name
(string): The user's name. (optional) -
email
(string): The user's email address. (optional) -
**Additional fields**
: Additional fields can be added to the user information object, these fields will be saved to the visitor's profile, however at this time, this information is not used by the chatbot nor the widget, but we are planning to add support for custom integrations and chatbot logic in the future.
-
Note, the name
and email
fields are optional, but at least one of them must be provided to identify the user, or
else the identify
method will not do anything.
Usage:
Chatflow.identify({ name: "John Doe", email: "john@example.com" });
positionLeft()
Description:
Positions the widget on the left side of the screen.
Usage:
Chatflow.positionLeft();
positionRight()
Description:
Positions the widget on the right side of the screen.
Usage:
Chatflow.positionRight();
togglePosition()
Description:
Toggles the widget's position between the left and right sides of the screen.
Usage:
Chatflow.togglePosition();
previewForm(formId)
Description:
Opens a preview of the form with the specified ID in the chat widget, this is the same method that is used to preview the form in the Form edit screen in the ChatFlow dashboard.
Usage:
Chatflow.previewForm("123");
openForm(formId, options)
Description:
Displays the form with the specified formId
in the chat widget and shows the message
as if the chatbot sent it.
Parameters:
-
options
(Object):-
message
(string): The user's name. (optional)
-
Note: We plan to add support for additional options, such as pre-filling the form fields, opening the form in a modal, allowing you to prompt the AI to generate a message instead of providing a static message, we will update the documentation once these features are available.
Usage:
Chatflow.openForm("123", {
message: "Please fill out this survey.",
});
Events
Available Events
Event Name | Description |
---|---|
opened |
Widget is opened. |
closed |
Widget is closed. |
maximized |
Widget size changed to maximized . |
minimized |
Widget size changed to minimized . |
halfed |
Widget size changed to halfed . |
positioned:left |
Widget position changed to the left side of the screen. |
positioned:right |
Widget position changed to the right side of the screen. |
size:changed |
Widget size was changed. (maximized , minimized , halfed ) |
size:cycled |
Widget size was cycled. (halfed -> minimized -> maximized , repeat) |
session:ended |
The chat session has ended (sets the end date for the conversations). |
message:sending |
Triggered when a chat message is being sent (has not reached server yet). |
message:sent |
Triggered when a chat message has been sent (reached server and saved). |
reply:requested |
Triggered when a response is requested from the chatbot (Typically triggers right after after message:sent ). |
reply:received |
Triggered when a response is received from the chatbot. |
identified |
The user has been identified in the chat session. (Either by end-user or by the identify() method). |
command |
A /command was triggered in the chat, event details includes command and arguments. |
info |
The /info command was triggered in the chat, event details includes debug information about the chatbot and widget. |
Listening for Events
document.addEventListener("DOMContentLoaded", function () {
// Enable debug mode
Chatflow.enableDebug(true);
// Open the widget
Chatflow.open();
Chatflow.on("message:sent", function (event) {
console.log("sent message to chatbot", event.detail);
});
Chatflow.on("reply:received", function (event) {
console.log("got reply from chatbot", event.detail);
});
Chatflow.on("positioned:right", function (event) {
console.log("Widget is positioned to the right");
});
Chatflow.on("positioned:left", function (event) {
console.log("Widget is positioned to the left");
});
Chatflow.on("minimized", function (event) {
console.log("Widget was minimized");
});
Chatflow.on("maximized", function (event) {
console.log("Widget was maximized");
});
Chatflow.on("halfed", function (event) {
console.log("Widget was halfed");
});
Chatflow.on("size:cycled", function (event) {
console.log("Widget size cyled to " + event.detail);
});
Chatflow.on("size:changed", function (event) {
console.log("Widget size changed to " + event.detail);
});
Chatflow.on("session:ended", function (event) {
console.log("Chat session has ended");
});
Chatflow.on("session:ended", function (event) {
console.log("Chat session has ended");
});
Chatflow.on("command", function (event) {
console.log("Command triggered", event.detail);
if (event.detail.command === "custom") {
console.log(
"Custom command triggered with arguments",
event.detail.arguments,
);
}
// Example: Command with no arguments - Set the input to a predefined message
if (event.detail.command === "lorem" && event.detail.arguments === "") {
console.log("Lorem ipsum command was triggered");
Chatflow.setInput(
"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
);
}
// Example: Command with some arguments - Send a message with lorem ipsum
if (event.detail.command === "lorem" && event.detail.arguments !== "") {
Chatflow.send(
"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
);
}
});
setInterval(() => {
Chatflow.cycleSize();
}, 1000);
setInterval(() => {
Chatflow.togglePosition();
}, 500);
});
Triggering Custom Events
Custom events can be emitted using the emit(event, value)
method and listened for using the on(event, callback)
method. These events allow for
custom integrations and behaviors based on widget interactions.
// Emit a custom event
Chatflow.emit("customEventName", {
some: "data",
});
Cookbook
Custom Widget Trigger Button
You can create a custom button to trigger the widget using the open
and close
methods.
<button id="open-widget">Open Widget</button>
<button id="close-widget">Close Widget</button>
<button id="toggle-widget">Toggle widget</button>
Remember to hide the default trigger button by setting the data-hide-toggle-button
attribute to true
on the iframe.
<script
id="chatflow-widget"
data-chatbot-id="your-chatbot-id"
data-hide-toggle-button="true"
src="https://chatflow.no/embed.js"
></script>
Now, you can add event listeners to the custom buttons to open, close, and toggle the widget.
document.getElementById("open-widget").addEventListener("click", function () {
Chatflow.open();
});
document.getElementById("close-widget").addEventListener("click", function () {
Chatflow.close();
});
document.getElementById("toggle-widget").addEventListener("click", function () {
Chatflow.toggleWidget();
});
Switching Widget Position
You can create a button to toggle the widget's position between the left and right sides of the screen using
the togglePosition
method.
<button id="toggle-position">Toggle Position</button>
document
.getElementById("toggle-position")
.addEventListener("click", function () {
Chatflow.togglePosition();
});
You may also want to explicitly set the widget's position using the positionLeft
and positionRight
methods.
<button id="position-left">Position Left</button>
<button id="position-right">Position Right</button>
document.getElementById("position-left").addEventListener("click", function () {
Chatflow.positionLeft();
});
document
.getElementById("position-right")
.addEventListener("click", function () {
Chatflow.positionRight();
});
Identifying Users
You can use the identify()
method to identify a user in the chat session by providing their name and email address.
This can be useful for pre-filling the user's name and email in the chat widget, if the user is logged in to your website.
Chatflow.identify({
name: "John Doe",
email: "john.doe@example.com",
});
Integrating with Forms
This guide will walk you through the process of capturing form field values, identifying the user, opening the chatbot, and sending a message based on the form values to provide a personalized shopping experience.
Scenario
In our hypothetical example, we want to use ChatFlow as a personalized shopping assistant.
We'll use the identify()
method to identify the user in the chat session, open()
to open the chatbot, and send()
to send a message to the chatbot with the user's preferences. based on the form field values.
For the purpose of this example, let's assume the user is looking for a shoe that is out of stock on your e-commerce site, your site has a "out of stock" form that users can fill out to be notified when the shoe is back in stock.
The form fields include the user's name, email, shoe size, and favorite color.
Step 1: Add the ChatFlow Widget to Your Website
First, add the ChatFlow widget to your website by including the script tag in your HTML. Make sure to
replace your-chatbot-id
with your actual chatbot ID.
<script
id="chatflow-widget"
data-open="false"
data-dark-mode="false"
data-chatbot-id="your-chatbot-id"
data-trigger-color="#000000"
data-trigger-text-color="#ffffff"
data-btn-open-text="Open"
data-btn-close-text="Close"
data-init="false"
src="https://chatflow.no/embed.js"
></script>
Note: The data-init="false"
and data-open="false"
attribute, the first is used to prevent the widget from
initializing automatically, and the second
is used to prevent the chatbot from opening automatically when the page loads.
We will initialize the widget manually and open it programmatically after the form is submitted, so we don't have to worry about the widget not being ready when we need it.
Step 2: Initialize the ChatFlow Widget Manually
Since you'll be controlling the chatbot programmatically, initialize the widget manually by adding the following JavaScript code:
document.addEventListener("DOMContentLoaded", function () {
Chatflow.initialize();
});
Step 3: Hook into the Form Submission
Next, hook into the form submission event. For this example, assume you have a form with the id="out-of-stock-form"
.
<form id="out-of-stock-form">
<div>
<label for="name">Name:</label>
<input type="text" id="name" required />
</div>
<div>
<label for="email">Email:</label>
<input type="email" id="email" required />
</div>
<div>
<label for="shoe-size">Shoe Size:</label>
<input type="text" id="shoe-size" required />
</div>
<div>
<label for="favorite-color">Favorite Color:</label>
<input type="text" id="favorite-color" required />
</div>
<button type="submit">Submit</button>
</form>
Add an event listener for the form submission:
document
.getElementById("out-of-stock-form")
.addEventListener("submit", function (event) {
event.preventDefault(); // Prevent the form from submitting normally
// Retrieve form field values
const name = document.getElementById("name").value;
const email = document.getElementById("email").value;
const shoeSize = document.getElementById("shoe-size").value;
const favoriteColor = document.getElementById("favorite-color").value;
});
Now that you have the form field values, you can start interacting with the ChatFlow widget.
Step 5: Identify the User and Open the Chatbot
Use the identify()
method to identify the user in the chat session, and open the chatbot using the open()
method.
Chatflow.identify({ name, email });
Chatflow.open();
Step 6: Send a Message to the Chatbot
Now we can use the collected form field values to send an initial message to the chatbot asking for a similar shoe.
Send a message to the chatbot using the send()
method, including the form field values in the message.
Chatflow.send(
`Hello, I'm looking for a shoe in size ${shoeSize} and color ${favoriteColor}. Can you help me find a similar one?`,
);
For the sake of this example, we're sending a simple message to the chatbot with the user's preferences.
If done correctly, the chatbot should respond with a recommendation based on the user's preferences, based on the knowledge base you've set up in ChatFlow.
In this scenario, your Chatbot would have been setup to crawl an E-commerce site to gather information about the products, then we can use this information to provide recommendations to the user based purely on their preferences and the information we have about the products.
Appearance
The appearance of the Chatflow widget can be customized using CSS variables. This allows for seamless integration with your website's design by altering colors, fonts, and other stylistic choices directly through CSS.
Customizable Properties
Default Color Generation behaviour
By default, the widget will generate these values based on the brand_color
and 'force_dark_mode' settings in the
chatbot settings.
The color generation is done by splitting the brand color into the corresponding HSL values, and then adjusting
the lightness
value to generate the primary and secondary colors.
Main colors
These are the primary colors used across the widget, including the primary and secondary colors, background colors, you can also adjust the lighten and darken values to adjust the color's lightness and darkness.
Base Colors
CSS Variable | Default Value | Description |
---|---|---|
--lighten |
20% |
How much to lighten the primary color. |
--darken |
-20% |
How much to darken the primary color. |
--primary-color-h |
217 |
Hue value for primary color. |
--primary-color-s |
91% |
Saturation value for primary color. |
--primary-color-l |
60% |
Lightness value for primary color. |
Light and Dark variants
When a primary color is generated, the widget will also generate a light and dark variant of the primary color, these are used for various elements in the widget, such as the chat bubbles and various hover states.
:root {
--primary-color--light: hsl(
var(--primary-color-h),
var(--primary-color-s),
calc(var(--primary-color-l) + var(--lighten))
);
--primary-color--dark: hsl(
var(--primary-color-h),
var(--primary-color-s),
calc(var(--primary-color-l) + var(--darken))
);
}
Explicitly Defined Colors
However, if you don't want to use the default color generation, you can explicitly define the colors of the main widget elements using the following CSS variables:
CSS Variable | Default Value | Description |
---|---|---|
--brand-primary |
var(--primary-color) |
Brand primary color. |
--brand-secondary |
var(--secondary-color) |
Brand secondary color. |
--brand-bg |
var(--background-color) |
Brand background color. |
--brand-bg-faint |
#f9fafb |
Faint brand background color. |
--brand-bg-alt |
#f3f4f6 |
Alternate brand background color. |
--brand-text |
black |
Text color for brand. |
--brand-text-alt |
#222 |
Alternate text color for brand. |
--brand-border |
#e5e7eb |
Brand border color. |
--brand-border-alt |
#e5e7eb |
Alternate brand border color. |
--chat-toggle-bg |
var(--brand-primary) |
Chat toggle button background color. |
--chat-toggle-text |
var(--brand-bg) |
Chat toggle button text color. |
--chat-user-bubble-bg |
var(--primary-color) |
Chat User bubble background color. |
--chat-user-bubble-text |
var(--brand-bg) |
Chat User bubble text color. |
--chat-user-bubble-border |
transparent |
Chat User bubble border color. |
--chat-ai-bubble-bg |
var(--brand-bg-alt) |
Chat AI bubble background color. |
--chat-ai-bubble-text |
var(--brand-text) |
Chat AI bubble text color. |
--chat-ai-bubble-border |
transparent |
Chat AI bubble border color. |
--chat-system-bubble-bg |
#e0f2fe |
Chat System bubble background color. |
--chat-system-bubble-border |
#cbd5e1 |
Chat System bubble border color. |
--chat-system-bubble-text |
#475569 |
Chat System bubble text color. |
--chat-messages-bg |
var(--brand-bg) |
Chat messages background color. |
--chat-window-bg |
var(--brand-bg) |
Chat window background color. |
--chat-window-border |
var(--brand-border) |
Chat window border color. |
--chat-footer-bg |
var(--brand-bg) |
Chat footer background color. |
--chat-footer-border |
var(--brand-border) |
Chat footer border color. |
--chat-input-bg |
#f3f4f6 |
Chat input background color. |
--chat-input-text |
#374151 |
Chat input text color. |
--chat-input-border |
var(--brand-border-alt) |
Chat input border color. |
--chat-header-bg |
var(--brand-bg) |
Chat header background color. |
--chat-header-border |
var(--brand-border) |
Chat header border color. |
--chat-header-text |
var(--brand-text) |
Chat header text color. |
--chat-typing-indicator-bg |
var(--brand-bg-alt) |
Chat typing indicator background color. |
--chat-typing-indicator-border |
var(--brand-border) |
Chat typing indicator border color. |
--chat-typing-indicator-text |
#6b7280 |
Chat typing indicator text color. |
--chat-send-button-bg |
var(--brand-bg) |
Chat send button background color. |
--chat-send-button-border |
transparent |
Chat send button border color. |
--chat-send-button-text |
var(--primary-color) |
Chat send button text color. |
--chat-button-bg |
transparent |
Chat button background color. |
--chat-button-border |
transparent |
Chat button border color. |
--chat-button-text |
#9ca3af |
Chat button text color. |
--chat-close-button-bg |
transparent |
Chat close button background color. |
--chat-close-button-border |
transparent |
Chat close button border color. |
--chat-close-button-text |
#9ca3af |
Chat close button text color. |
--chat-branding-bg |
var(--brand-bg-faint) |
Powered by ChatFlow background color. |
--chat-branding-border |
var(--brand-border) |
Powered by ChatFlow border color. |
--chat-branding-text |
#9ca3af |
Powered by ChatFlow text color. |
Injecting CSS Variables
To customize the appearance of the Chatflow widget, you can inject CSS variables into the widget's iframe snippet using
the
injectCss()
method.
The injectCss()
method takes two arguments:
-
variables
(Object): An object containing the CSS variables to inject, key-value pairs where the key is the CSS variable name and the value is the CSS variable value (hex, rgb, hsl, etc) -
theme
(String): The theme to apply the CSS variables to. Can be either "light" or "dark".
document.addEventListener("DOMContentLoaded", function () {
// Note: The widget must be initialized before injecting CSS variables,
// since the event handler that handles the CSS Injection configured after the widget initialization.
Chatflow.on("iframe:init", function (event) {
// Inject custom CSS variables for the "light" theme, you may specify "dark" for the dark theme.
Chatflow.injectCss(
{
"--brand-bg": "#ff0000",
},
"light",
);
});
});
Light Theme (Default)
Here is an excerpt of the default light theme CSS variables used in the Chatflow widget, you can override any of these variables to customize the appearance of the widget.
.theme-light {
--lighten: 20%;
--darken: -20%;
--primary-color-h: 217;
--primary-color-s: 91%;
--primary-color-l: 60%;
--primary-color: hsl(
var(--primary-color-h),
var(--primary-color-s),
var(--primary-color-l)
);
--primary-color--light: hsl(
var(--primary-color-h),
var(--primary-color-s),
calc(var(--primary-color-l) + var(--lighten))
);
--primary-color--dark: hsl(
var(--primary-color-h),
var(--primary-color-s),
calc(var(--primary-color-l) + var(--darken))
);
--secondary-color: hsl(
calc(var(--primary-color-h) + 180),
var(--primary-color-s),
var(--primary-color-l)
);
/* Brand */
--brand-primary: var(--primary-color);
--brand-secondary: var(--secondary-color);
--brand-bg: white;
--brand-bg-faint: #f9fafb;
--brand-bg-alt: #f3f4f6;
--brand-text: black;
--brand-text-alt: #222;
--brand-border: #e5e7eb;
--brand-border-alt: #e5e7eb;
/* Chat toggle */
--chat-toggle-bg: var(--brand-primary);
--chat-toggle-text: var(--brand-bg);
/* Chat user bubble */
--chat-user-bubble-bg: var(--primary-color);
--chat-user-bubble-text: var(--brand-bg);
--chat-user-bubble-border: transparent;
/* Chat AI bubble */
--chat-ai-bubble-bg: var(--brand-bg-alt);
--chat-ai-bubble-text: var(--brand-text);
--chat-ai-bubble-border: transparent;
/* Chat system bubble */
--chat-system-bubble-bg: #e0f2fe;
--chat-system-bubble-border: #cbd5e1;
--chat-system-bubble-text: #475569;
/* Chat messages */
--chat-messages-bg: var(--brand-bg);
/* Chat window */
--chat-window-bg: var(--brand-bg);
--chat-window-border: var(--brand-border);
/* Chat Footer */
--chat-footer-bg: var(--brand-bg);
--chat-footer-border: var(--brand-border);
/* Chat input */
--chat-input-bg: #f3f4f6;
--chat-input-text: #374151;
--chat-input-border: var(--brand-border-alt);
/* Chat header */
--chat-header-bg: var(--brand-bg);
--chat-header-border: var(--brand-border);
--chat-header-text: var(--brand-text);
/* Chat typing indicator */
--chat-typing-indicator-bg: var(--brand-bg-alt);
--chat-typing-indicator-border: var(--brand-border);
--chat-typing-indicator-text: #6b7280;
/* Send button */
--chat-send-button-bg: var(--brand-bg);
--chat-send-button-border: transparent;
--chat-send-button-text: var(--primary-color);
/* Chat Button */
--chat-button-bg: transparent;
--chat-button-border: transparent;
--chat-button-text: #9ca3af;
/* Close button */
--chat-close-button-bg: transparent;
--chat-close-button-border: transparent;
--chat-close-button-text: #9ca3af;
/* Branding */
--chat-branding-bg: var(--brand-bg-faint);
--chat-branding-border: var(--brand-border);
--chat-branding-text: #9ca3af;
}
Dark Theme
Here is an excerpt of the default dark theme CSS variables used in the Chatflow widget, you can override any of these variables to customize the appearance of the widget when in dark mode.
.theme-dark {
--lighten: 5%;
--darken: -5%;
--primary-color-h: 217;
--primary-color-s: 91%;
--primary-color-l: 30%;
--primary-color: hsl(
var(--primary-color-h),
var(--primary-color-s),
var(--primary-color-l)
);
--primary-color--light: hsl(
var(--primary-color-h),
var(--primary-color-s),
calc(var(--primary-color-l) + var(--lighten))
);
--primary-color--dark: hsl(
var(--primary-color-h),
var(--primary-color-s),
calc(var(--primary-color-l) + var(--darken))
);
--secondary-color: hsl(
calc(var(--primary-color-h) + 180),
var(--primary-color-s),
var(--primary-color-l)
);
/* Brand */
--brand-primary: var(--primary-color);
--brand-secondary: var(--secondary-color);
--brand-bg: #1e1e1e; /* Background color for dark mode */
--brand-bg-faint: #2e2e2e; /* Faint background color for dark mode */
--brand-bg-alt: #333; /* Alternate background color for dark mode */
--brand-text: white; /* Text color for dark mode */
--brand-text-alt: #ddd; /* Alternate text color for dark mode */
--brand-border: #444; /* Border color for dark mode */
--brand-border-alt: #555; /* Alternate border color for dark mode */
/* Update chat toggle, chat user bubble, chat AI bubble, and other components for dark mode */
--chat-toggle-bg: var(--primary-color);
--chat-toggle-text: var(--brand-text);
--chat-user-bubble-bg: var(--primary-color);
--chat-user-bubble-text: var(--brand-text);
--chat-user-bubble-border: transparent;
--chat-ai-bubble-bg: var(--brand-bg-alt);
--chat-ai-bubble-text: var(--brand-text);
--chat-ai-bubble-border: transparent;
/* Chat System Bubble */
--chat-system-bubble-bg: #1e1e1e; /* Dark background color */
--chat-system-bubble-border: #444; /* Dark border color */
--chat-system-bubble-text: #ddd; /* Dark text color */
/* Chat Messages Area */
--chat-messages-bg: var(--brand-bg);
/* Chat Window */
--chat-window-bg: #1e1e1e;
--chat-window-border: #444;
/* Chat Footer Area */
--chat-footer-bg: #1e1e1e;
--chat-footer-border: #444;
--chat-input-text: white;
/* Chat Input Area */
--chat-input-bg: #333;
--chat-input-placeholder: #aaa;
--chat-input-border: #444;
/* Chat Header */
--chat-header-bg: #1e1e1e;
--chat-header-border: #444;
--chat-header-text: white;
/* Chat Typing Indicator */
--chat-typing-indicator-bg: #333;
--chat-typing-indicator-border: #444;
--chat-typing-indicator-text: #ccc;
/* Chat Branding */
--chat-branding-bg: #2e2e2e;
--chat-branding-border: #444;
--chat-branding-text: #ddd;
/* Chat Button */
--chat-button-bg: transparent;
--chat-button-border: transparent;
--chat-button-text: var(--brand-text);
/* Chat Send Button */
--chat-send-button-bg: transparent;
--chat-send-button-border: transparent;
--chat-send-button-text: var(--brand-text);
/* Chat Close Button */
--chat-close-button-bg: transparent;
--chat-close-button-border: transparent;
--chat-close-button-text: #ccc;
}
Dark Mode
Note on In ChatFlow, "Dark mode" refers to the widget's appearance when the data-dark-mode
attribute is set to true
, or when
the chatbot Force Dark Mode?
setting is enabled in the ChatFlow dashboard.
ChatFlow does yet automatically switch to dark mode based on the user's system preferences.