Learn how to integrate ChatBotKit's widget onto your website to enhance user experience. Easily customize the widget to fit your needs with various options.

In addition to the Slack and Discord, ChatBotKit also offers a Widget integration, which allows users to embed ChatBotKit directly on any website. This feature allows users to engage with AI chatbots directly from a website, providing a convenient and seamless experience for customers. The widget integration is fully customizable, allowing users to tailor the appearance and functionality of their chatbot to fit their specific needs.


Follow these steps to create a new website widget:

  1. Go to Integrations and then click the Create Widget Integration button.
  2. Fill in the Name and provide your chatbot Backstory.
  3. Connect to an existing Bot or select a Model, Dataset and Skillset.
  4. Save the integration by clicking the "Create" button.

Now that the integration is saved you can embed it into a website.

  1. Click the "Install" button.
  2. Copy the widget snippet (code).
  3. Paste the snippet into your website.

⚠️ There are two widget SDKs. The latest SDK is V2 which simplifies the embedding and theming and it is the recommended way to embed ChatBotKit in your website.

Widget V2 is the default and recommended way to embed ChatBotKit in your website. It simplifies embedding and theming, and supports greater customization than V1. All UI changes can be directly applied from the widget configuration options.


Markdown Support

Both the Intro and each individual message support markdown formatting. This means that you can include links, images, tables and other embeddable content.


The widget integration offers a variety of themes to choose from. By default, the theme is set to "light". You can customise the primary color. Additional themes are available in ChatBotKit Theme Gallery.

Themes are an extremely useful tool for crafting bespoke chat user experiences without the need for coding. By personalizing the look and feel of your chat interface, you can enhance the user experience and create a more engaging and interactive environment for your users. With themes, you can easily tailor your chatbot to match your brand's aesthetic, incorporating your company's logo, color palette, and fonts. Additionally, you can experiment with different themes to identify which designs are most effective at engaging your target audience. With the ability to customize every aspect of your chat user experience through themes, the possibilities for creating an immersive and engaging chatbot are endless.


The widget integration allows you to customize the icons displayed within the chatbot interface. There are four types of icons that can be customized: the bar icon, the user icon, the bot icon and the button icon. Each of these icons can be set to a custom image.

To customize the icons:

  1. Go to the Integrations page and select your widget integration.
  2. Scroll down to the "Icons" section.
  3. Customize the icons by selecting the icon files from your disk.

By customizing the icons, you can create a more personalized and engaging chat experience for your users. Incorporating your brand's iconography or using fun and expressive emojis can help to create a chatbot that feels more like a natural conversation partner.

Origin Checks

Your Widget can be configured to only run on specific websites. This is a recommended security feature to ensure that chat sessions can only be initialized from your website alone.

The origin is the web page address without the path (referred to as the "base URL" or "root URL."). It is the portion of the URL that includes the protocol (e.g. "http" or "https"), the domain name, and any subdomains (e.g. "www"), but not the specific page or resource being accessed (the path).

It is advisable to use this feature to ensure that your Widget can only be used from specific locations.

You can use comma (,) to specify multiple origins.


The streaming feature allows for continuous updates to the chatbot user interface. This is useful for scenarios where the chatbot is being used for real-time communication, such as customer support. To enable this feature, simply toggle the stream option when updating your widget integration.


When the verbose option is turned on, the widget will display additional context information such as what the chatbot is searching for or what actions it executes. This option improves the overall user experience.

Turning Branding Off

Customers on our Pro, Team, and Ultimate tiers have the option to turn off the "Powered By ChatBotKit" branding in their Widget integrations. This option can be found in the "Advanced Options" section of the Widget configuration. To turn off the branding, simply toggle the switch.

⚠️ Please note that this option is only available to customers on our Pro, Team, and Ultimate tiers.

Embedding The Widget

The Widget can be easily embedding with a script tag like this:

<script src="https://static.chatbotkit.com/integrations/widget/v2.js" data-widget="{WIDGET_ID}"></script>

Additional parameters (see next section) can also be passed as data attributes. For example:

<script src="https://static.chatbotkit.com/integrations/widget/v2.js" data-widget="{WIDGET_ID}" data-open="true"></script>

If no data-widget property is present then the SDK will be initialised but no widget will be instantiated. In this case you will need to instantiate the widget using its HTML custom tag.

Embedding The Frame

You can also embed the Widget frame directly. This method gives you to a greater degree of control over the widget.

The following parameters can be passed to the frame or the custom HTML tag no matter the method of embedding:

openBoolean property to indicate if widget should be open
sessionThe session for this frame.
barIconThe URL for the bar icon
userIconThe URL for the user icon
botIconThe URL for the bot icon
buttonIconThe URL for the button icon

There are two ways to embed the frame: directly and using the SDK with custom HTML tag.

Direct Embedding

Here is a quick example how to embed the Widget iframe directly:

<iframe src="https://static.chatbotkit.com/integrations/widget/{WIDGET_ID}/frame?...parameters"></iframe>

Use your own widget integration id instead of {WIDGET_ID}.

A working example of this embedding technique can be found here.

SDK Embedding

It is also possible to embed the widget iframe with the SDK. Follow the same steps as normal widget setup but do not specify the widget id. For example:

<script src="https://static.chatbotkit.com/integrations/widget/v2.js"></script>

Notice that we simply include the ChatBotKit SDK but we do not indicate which widget we want to load. Now we can include the widget anywhere on the page by using a custom tag like this:

<chatbotkit-widget id="my-widget" widget="{WIDGET_ID}" ...parameters/>

The custom widget tag also supports several built-in methods which allow you to interact with the widget. For example:

const iframe = document.getElementById("chatbotkit-widget"); iframe.restartConversation();

The following methods are supported:

restartConversationRestarts the current conversation

A working example of this embedding technique can be found here.

Sending Messages

Developers can use the postMessage API to send messages to the ChatBotKit Widget frame. This allows for programmatic interaction with the chatbot. To use this API, developers must have access to the iframe element containing the Widget frame. Once access is granted, developers can use the following code to send a message:

const iframe = document.getElementById("chatbotkit-widget-frame"); iframe.contentWindow.postMessage({ type: "type", props: {} }, "*");

The postMessage API can be used to trigger various actions and events within the Widget frame.

The following event types are supported:

restartConversation{}Restarts the current conversation

Developers can use this API to create more dynamic and interactive chatbot experiences for their users.

Continuous Chat Sessions

The ChatBotKit Widget supports continuous user sessions. A single session is one continuous conversation with a chat bot. Sessions are preserved across tabs and windows and automatically synchronized. This means the user can continue the conversation even when navigating to a different part of your website or switching tabs.

This is often the expected best possible experience for your end customers. Still, there are times when you may want to control when and how to chat sessions are created. In these situations, you can use the session parameter to define your unique identifier to distinguish between separate continuous conversations.

The session parameter can be any value - an id or just a random sequence of characters. By default each user gets a unique session every day. Once you set up the session, conversations will continue on the same conversation channel. For example, you may want to distinguish chat sessions that have started from one area of your website from others. Or perhaps, your landing pages might need a completely new chat session. In this case, you can use the session parameter to start separate continuous chats.

It is also equally possible that every page has its own chat session. This means the session will not be preserved when navigating different pages. To do so, use the current page address for the session, for example.

You can also pass the special value none. This means that you don’t want any session. This is means that no matter how many times a user visit the widget they will have a fresh conversation window.

In summary here is a table for all possible session values.

When no value provided the session is pinned to the current day
The session is pinned to the provided string.
noneNo session - no history

Widget V1 (deprecated)

⚠️ Widget V1 is deprecated. While we will keep hosting the V1 version we encourage ChatBotKit customers to move to V2 which provides easier embedding and many additional features.

You can customize v1 widgets by providing extra dataset properties (default), script URL hash or script URL query parameter. The following options are available for customisation:

widgetThe widget integration id.
sessionOptional unique session identifier. By default we will assign a session that last one day.
captionThe text displayed inside the button.
iconThe icon (emoji / URL) displayed inside the button.
themeSelect widget theme: {% list("availableThemes") %}.
introOptional introductionary text to include on top of the conversation. Supports markdown.
hostOptional host to use for ChatBotKit API. If not specified, the host is automatically detected.
possitionUtility option to quickly possition the widget at the top-left, top-right, bottom-left or bottom-right (default) part of the screen.

Customisation by HTML Data Attributes

To change an option simply supply it as an extra URL query parameter. For example to change the "caption" option do the following:

<script id="chatbotkit-widget" src="<https://static.chatbotkit.com/integrations/widget/v1.js>" data-widget="clcrog2pw1001tyfrrv8yyk3g" data-caption="Open Chat" ></script>

Customizations by URL Hash Parameters

To change an option simply supply it as an extra URL hash parameter. For example to change the "caption" option do the following:

<script id="chatbotkit-widget" src="<https://static.chatbotkit.com/integrations/widget/v1.js#widget=clcrog2pw1001tyfrrv8yyk3g&caption=Open+Chat>" ></script>

Customizations by URL Query Parameter

To change an option simply supply it as an extra URL query parameter. For example to change the "caption" option do the following:

<script id="chatbotkit-widget" src="<https://static.chatbotkit.com/integrations/widget/v1.js?widget=clcrog2pw1001tyfrrv8yyk3g&caption=Open+Chat>" ></script>

Customizations by Global Object

Alternatively, you can create a global object called chatbokitWidgetConfiguration. This object must be instantiated before loading the widget script. For example:

<script> window.chatbokitWidgetConfiguration = { options: { caption: 'Open Chat', icon: '❤️', }, } </script> <script id="chatbotkit-widget" src="<https://static.chatbotkit.com/integrations/widget/v1.js?widget=clcrog2pw1001tyfrrv8yyk3g>" ></script

Customizing The Button Style

The easiest way to customize the button style is with CSS and CSS variables. The following CSS variables are supported:

--button-font-familyCustomise the button font family.
--button-font-sizeCustomise the button font size.
--button-bg-colorCustomise the button background color.
--button-fg-colorCustomise the button foreground color.
--button-bg-hover-colorCustomise the button background color when hovered.
--button-fg-hover-colorCustomise the button foreground color when hovered.
--button-icon-image-sizeThe size of the width/height of the image for the button icon if an image url is used.
--button-icon-text-sizeThe size of the font size of the text for the button icon if symbol or emoji used.
--button-align-selfOptional property to align the button within the widget. You can use start to align it to the left or end (default) to align it to the right.
--button-border-widthThe border width of the button in default state.
--button-border-colorThe border color of the button in default state.
--button-border-open-widthThe border width of the button in open state.
--button-border-open-colorThe border color of the button in open state.
--wrapper-widthThe maxium width of the widget when opened.
--wrapper-heightThe maximum height of the widget when opened.
--frame-border-widthThe border width of the chat window when opened.
--frame-border-colorThe border color of the chat window when opened.

Customization can be directly applied with CSS. For example:

chatbotkit-widget { --button-bg-color: yellow; --button-fg-color: black; }

Full Widget Customization Example

Here is a full example of how to customize the widget using varies methods and options:

<style> chatbotkit-widget { --button-bg-color: yellow; --button-fg-color: black; } </style> <script> window.chatbokitWidgetConfiguration = { options: { caption: 'Open Chat', icon: '❤️', }, } </script> <script id="chatbotkit-widget" src="<https://static.chatbotkit.com/integrations/widget/v1.js?widget=clcrog2pw1001tyfrrv8yyk3g>" ></script