Widget

In addition to the Slack, Discord and WhatsApp, ChatBotKit also offers a Widget integration, which allows users to embed ChatBotKit directly on any website or other platforms where iframe embedding is allowed. 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.

Setup

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 optional description.
3. Connect to an existing Bot or select a Backstory, 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.

Features

Markdown

Both the intro and each individual message support markdown formatting. This means that you can include links, images, tables and other embeddable content. The following syntax is supported.

Themes

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 the Examples and you can even build your own via the Theme Builder.

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.

Layouts

The ChatBotKit AI Widgets supports a number of different layouts. A layout indicates how the widgets needs to be rendered on the screen. The default layout is popover, meaning that the popup is over the widget button. You can also selected the popout layout where the popup is in the middle of the screen.

The widget layout can also be controlled via the layout property that can be passed during the widget initialization. It can be also setup manually when creating the widget component.

Layouts allow to create more interesting interfaces to support various types of scenarios such as AI-native search interfaces and more.

Icons

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.

Origins

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.

Languages

Configuring multiple languages for your widget is a straightforward process. You have the flexibility to add as many languages as you want to cater to a global audience. To do this, you simply need to type out the names of the languages you wish to include, and arrange them in the order you desire.

Once you have completed these steps and saved the widget, our system will automatically update your internationalisation settings. This automatic update ensures that your widget remains current and user-friendly, providing a seamless experience for users across different regions.

The result of this configuration is that your users will now have the ability to interact with the widget by selecting their language of choice from the list. This feature is crucial in ensuring your widget is accessible and user-friendly, allowing users to engage with it in the language they are most comfortable with. This not only enhances user experience but also broadens the reach of your widget to a more diverse audience.

Language Selection

Users can choose their preferred language for the widget from a list, with the first language set as the default. To select a different default language when embedding the frame, use the ?language= or ?locale= query parameters. For example, appending /frame?language=spanish to your frame's URL will set Spanish as the default language.

Streaming

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.

Verbosity

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.

Tools

ChatBotKit's widget includes a set of auxiliary tools that can be included with each message produced by the AI bot. These tools include the ability to copy the message to the clipboard, as well as a thumbs up and thumbs down rating system.

Enabling the Tools feature can be done by toggling the "Tools" option in the widget configuration. When enabled, each message produced by the bot will include a small toolbar with the auxiliary tools. This allows users to easily copy important information from the chat interface or provide feedback on the quality of the AI bot's responses.

The copy to clipboard feature is particularly useful for chatbots that are used for customer support or e-commerce, as it allows users to easily copy important information such as order numbers or tracking information without having to leave the chat interface. Additionally, the thumbs up and thumbs down rating system can be a useful tool for gathering feedback from users on the quality of the AI bot's responses. This feedback can be used to improve the chatbot over time and ensure that it is providing the best possible experience for users.

Unfurling

URL unfurling is a feature that allows the ChatBotKit widget to display a preview of a URL that has been shared in the chat. This preview typically includes a title, description, and image associated with the URL. This feature is particularly useful for chatbots that are used for customer support or e-commerce, as it allows chat bots to easily share product pages or other relevant information in a graphical way without forcing the user to leave the chat interface.

To enable URL unfurling, simply instruct the bot to include the URL in a message. The ChatBotKit widget will automatically detect the URL and generate a preview.

Contacts

ChatBotKit's widget also offers a Contact Collection feature, which allows customers to collect the name and email address of visitors who are using the widget.

When enabled, the Contact Collection feature will prompt visitors to enter their name and email address before starting a chat session with the chatbot. The collected information will be stored in ChatBotKit's conversation and can be accessed by the customer.

The Contact Collection feature is particularly useful for businesses that want to collect leads or customer information. By collecting the name and email address of visitors who are using the chatbot, businesses can follow up with potential customers and build a relationship with them over time.

Forms

ChatBotKit's AI Widget also supports HTML forms, enabling a direct and efficient method for collecting structured information from users during conversations. This feature enhances the interactivity of the ChatBotKit AI Widget, making it possible to gather data, feedback, and other user inputs through familiar form interfaces within the chat environment.

To implement a form within a conversation, the user (or the developer configuring the AI Widget) must provide clear instructions to the AI agent specifying that a form is required for a particular type of interaction. The AI will then generate and display the form directly in the chat widget.

Consider the following example backstory:

Collect the customer preferences using the following form:

<form>
<input name="abc" placeholder="xyz"/>
<select name="qwe">
<option value="opt1">Optionion 1</option>
<option value="opt2">Optionion 2</option>
<option value="opt3">Optionion 3</option>
</select>
</form>

Of course this example provides a simple starting point. More complex scenarios can be achieved with better structured backstories.

The forms feature can also be used in the initial message as well. This is also a good way to start the conversation - i.e. by allow for the bot to collect custom information before the collection starts.

Branding

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.

Media

The ChatBotKit widget supports the display of images and videos as long as they are generated by the chatbot in markdown format. The markdown image embedding syntax applies for both cases. Customers who wish to display media need to instruct the chatbot to output images, YouTube videos, or any other form of video and audio content using the markdown image embedding format: ![](url).

By using this syntax, chatbot creators can easily integrate visuals and multimedia into their chatbots. This can be particularly useful for chatbots that are used for e-commerce or customer support, as it allows chatbots to easily share product images or instructional videos without forcing the user to leave the chat interface. Additionally, by incorporating multimedia into your chatbot, you can create a more engaging and interactive experience for your users, helping to improve customer satisfaction and engagement.

Math

The ChatBotKit widget offers comprehensive support for mathematical expressions through LaTeX syntax. This powerful feature enables the seamless integration of complex mathematical formulas and equations within the chat interface, enhancing the widget's capabilities for educational, scientific, or technical applications. Users can effortlessly incorporate a wide range of mathematical notations, from simple algebraic expressions to advanced calculus formulas, ensuring precise and visually appealing representation of mathematical concepts.

Carousel

The ChatBotKit widget includes an innovative carousel feature that allows users to present information in a visually engaging way. This feature automatically identifies suitable content for carousel display, transforming it into a scrollable list of items that enhances user interaction. Ideal for showcasing products, options, or any list-oriented data, the carousel seamlessly integrates with other widget functionalities, offering an immersive and interactive user experience. By leveraging this tool, businesses can create dynamic and intuitive interfaces perfect for shopping platforms and beyond, facilitating a more engaging and streamlined interaction with users.

Attachments

Once the attachment feature is activated, your widget will gain the capability to receive various file attachments, including but not limited to images, documents, and other types of files. These attachments are integrated into the conversation, enhancing its richness and interactivity. Additionally, attachments can be processed by specialized Skillsets, such as Vision Skillset Actions and other similar tools. This functionality allows attachments to be directly utilized within widgets, enabling the creation of robust troubleshooting chatbots and other advanced applications.

Client-side Functions

The “Client-side Functions” feature is a versatile enhancement to the ChatBotKit AI Widgets, designed to bridge the gap between your application logic and ChatBotKit AI bots. This powerful tool enables direct interactions between your user interface and the AI, facilitating real-time data updates and dynamic responses based on user interactions. Whether it’s adjusting to new user inputs, such as changing locations in a weather app, or processing live data feeds, “Client-side Functions” ensure that your AI agent remains synchronized with the application’s state, delivering a seamless and responsive user experience. This feature is ideal for developers looking to create more intuitive and interactive applications by embedding advanced AI capabilities directly into their existing systems.

Messages

You can pass some initial contextual messages before establishing a chat session. These message will be included as part of the conversation and will be taken into account. There are some limitations, such as only user messages can be passed in. This is to prevent model hallucination and other types of injection attacks.

For detailed instructions how to pass meta data review our tutorial.

Meta-data

All conversations initiated through the widget can be associated with specific meta-data. This meta-data can include information about the user, the context of the conversation, or any other relevant data. The meta-data is passed to the widget during its initialisation and can be used to personalize the chat experience or to provide context for the AI bot.

For detailed instructions how to pass meta data review our tutorial.

Caching

By default the Widget uses an aggressive caching policy the performance. We cache the widget page for maximum of 60 seconds. This behaviour can be turned off by setting cache property to false . This change can be done with URL query parameters or when embedding the widget through the widget component properties, data properties and all other available configuration mechanisms.

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.

Embedding The Widget

The recommended way to embed the widget is through the Widget SDK 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. For example:

<!-- embed the widget sdk -->
<script src="https://static.chatbotkit.com/integrations/widget/v2.js"></script>
<!-- instantiate a widget somewhere inside your application -->
<chatbotkit-widget widget="{WIDGET_ID}" open="true"/>

Embedding The Frame

You can also embed the Widget frame directly. This method gives you to a greater degree of control over the widget without the need to include the SDK. For example:

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

Because the widget frame is directly embedded we can also control how the widget is displayed. For example the following code puts the frame in fullscreen:

<iframe src="https://static.chatbotkit.com/integrations/widget/{WIDGET_ID}/frame" style="position:absolute;top:0;left:0;bottom:0;right:0;width:100%;height:100%"></iframe>

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 widget = document.getElementById("chatbotkit-widget");
widget.restartConversation();

The following methods are supported:

The following getters and setters are also supported:

Developers can also subscribe to the following events:

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

Widget Parameters

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

Advanced Topics

Widget Frame Direct Communication

Developers can use the postMessage API to send messages to the ChatBotKit Widget frame. This allows for an alternative programmatic interaction. 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: "restartConversation", props: {} }, "*");

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

The following event types are supported:

Similarly, developers can receive events via the postMessage API as well. Here is an example:

window.addEventListener('message', (event) => {
  if (event.origin === 'https://static.chatbotkit.com') {
    // TODO: process event
  }
});