Widget SDK

The ChatBotKit Widget SDK enables the initialization and configuration of ChatBotKit AI Widgets, allowing for either automatic or manual setup.

Embedding (v2)

The fastest method to install and display a ChatBotKit AI Widget is to incorporate the Widget SDK script and provide configuration parameters using data properties. For instance:

Additional widget properties, which are detailed below, can also be specified as data attributes. For example:

If the data-widget property is absent, the SDK will initialize but not instantiate any widget. In this scenario, you must instantiate the widget using a custom HTML tag. For example:

Data Attributes

All widget properties can be set as data-* attributes on the script tag or as attributes on the <chatbotkit-widget> element. Below is the full list of supported attributes:

For example, to position the widget in the bottom-left corner with a custom placeholder:

The same attributes work on the custom element:

ChatBotKit Global Object (v2)

The ChatBotKit Global Object is a JavaScript variable available globally, created immediately upon execution of the widget script. It provides quick access to the widget instance created through automatic initialization, rather than through the chatbotkit-widget custom HTML tag.

Properties

• instance: ChatBotKitWidget|null - Returns the current widget instance. If the widget is not yet ready, this property will return null instead.
• instancePromise: Promise<ChatBotKitWidget> - Returns a promise that resolves to the widget instance. This property allows for convenient use of await to access the instance once it becomes available. It is particularly useful for performing initialization or other tasks on the widget as soon as it is made available.

Window Properties

• chatbotkitWidgetConfiguration: object - This global variable can be used to add or override existing configuration properties, including the widget ID and other properties discussed in this document. It accepts a params key for widget attributes and a style key for custom CSS overrides.

Window Events

• chatbotkitWidgetInit, (event: { target: ChatBotKitWidget }) - The event is dispatched to the window once the SDK is initialized and the widget becomes available. This method is particularly useful for performing initialization or other tasks on the widget as soon as it is ready.

Window Functions

• chatbotkitWidgetInit(instance: ChatBotKitWidget) -> void - This is a global function that, if present, will be called when the widget is initialized and available.

ChatBotKit Widget (v2)

The ChatBotKit Widget is a custom HTML element that functions like standard HTML elements, but it also includes additional helper methods and properties for interacting with the AI widget.

Properties

• ready: boolean (read-only) - Indicates whether the widget is ready for interaction.
• readyPromise: Promise<boolean> (read-only) - A promise that resolves when the widget is ready. Useful for awaiting widget readiness before performing operations.
• messages: Message[] | null - An array of messages currently displayed inside the widget. You can update this array by assigning a new value to this property. Note that modifying the array of messages does not equate to sending a message from the user. Only messages sent by the user are accepted as part of the conversation when it is created.
• notifications: Record<string, NotificationDefinition | null> - An object containing notifications to be displayed alongside the conversation. Notifications will appear in the message peek when the widget is closed, and also if they have not yet been seen.
• functions: Record<string, FunctionDefinition | null> | null - An object containing function definitions available to the AI bot. You can modify these functions by directly assigning new values to this property.
• contact: Contact | null - Contact information associated with the widget session.
• meta: Record<string, unknown> | null - Any meta information that will be included when the conversation is created.
• open: boolean - A property that can be used to verify or ensure that the widget is open.
• widget: string - The ID of the widget to be used for this instance.

Methods

• hide() -> void - Hides the widget by changing its visibility. Does not toggle the open state.
• show() -> void - Shows the widget by changing its visibility. Does not toggle the open state.
• restartConversation() -> void - Restarts the current conversation. Clears all messages and resets the conversation session.
• initiateMessage(props: InitiateMessageOptions) -> void - Initiates a new message. The optional text property pre-fills the message input.
• sendMessage(props: SendMessageOptions) -> void - Sends a message on behalf of the end-user. Set hidden to true to hide the message from the conversation UI. Set respond to true to trigger a bot response.
• maximize() -> void - Maximizes the widget to take up more screen space.
• minimize() -> void - Minimizes the widget back to its default size.
• render(props: RenderOptions) -> void - Renders custom content inside the widget.
• registerFunctions(functions: Record<string, FunctionDefinition | null>) -> void - Registers additional functions with the widget. Functions are merged with any existing registrations.
• unregisterFunctions(functions: string[]) -> void - Unregisters functions by their names.
• assignContact(props: Contact) -> void - Assigns contact information to the widget session. This is a legacy method; prefer setting the contact property directly.

Events

• connect, (event: { target: ChatBotKitWidget }) - Triggered when the widget element is added to the DOM.
• ready, (event: { target: ChatBotKitWidget }) - Triggered when the widget is ready for interaction.
• send, (event: { target: ChatBotKitWidget, data: Message }) - Triggered when a message is sent by the end-user or through the sendMessage method.
• receive, (event: { target: ChatBotKitWidget, data: Message }) - Triggered when a message is received from the bot.
• disconnect, (event: { target: ChatBotKitWidget }) - Triggered when the widget element is removed from the DOM.

Using the SDK Packages

The widget works out of the box with just the embedded script tag, but for more advanced use-cases two companion npm packages are available. The @chatbotkit/widget package provides TypeScript type definitions for the widget custom element, and the @chatbotkit/react package provides React hooks for interacting with widget instances. You can use either or both depending on your stack.

@chatbotkit/widget - TypeScript Types

The @chatbotkit/widget package gives you type-safe access to every property, method, and event described above. This is useful when working with the widget directly in a TypeScript project.

Installation

Importing Types

Type Reference

Global Augmentations

The package augments the global Window interface and HTMLElementTagNameMap. This means document.querySelector('chatbotkit-widget') returns a properly typed ChatBotKitWidgetElementV2 element and window.chatbotkitWidget is typed as ChatBotKitGlobalObject - no manual casting required.

@chatbotkit/react - React Hooks

The @chatbotkit/react package provides React hooks that wrap the widget instance lifecycle for you. The hooks handle waiting for the widget to be ready, managing state updates, and cleaning up on unmount.

Installation

useWidgetInstance

Returns the widget instance once it is ready. Optionally accepts a CSS selector to target a specific widget element.

You can also pass a selector to target a specific widget element when multiple widgets are on the page:

useWidgetInstanceFunctions

Sets the active functions on the widget instance. The functions are applied whenever the instance becomes available or the functions value changes. The entire set of functions is replaced on each update, so pass the complete set of functions you want registered.

Accepts an options object with:

• functions - An object mapping function names to FunctionDefinition objects (or null to remove a function)
• selector - Optional CSS selector to target a specific widget element (defaults to the first chatbotkit-widget element)

When multiple widgets are on the page, use selector to target a specific one:

useWidgetInstanceNotifications

Sets the active notifications on the widget instance. Notifications are applied whenever the instance becomes available or the notifications value changes.

Accepts an options object with:

• notifications - An object mapping notification IDs to NotificationDefinition objects (or null to remove a notification)
• selector - Optional CSS selector to target a specific widget element (defaults to the first chatbotkit-widget element)

When multiple widgets are on the page, use selector to target a specific one:

Debugging

The widget supports debug flags that can be set on the window object before the widget script loads. These enable console logging for troubleshooting.

All messages are prefixed with [ChatBotKit Widget]. Errors are always written to console.error regardless of these flags.

Session Persistence

By default the widget saves its open state to sessionStorage under the key chatbotkit-widget-open. When the page is reloaded within the same browser session, the widget restores the previous open/closed state after a short delay. This means a user who had the widget open will see it reopen automatically on navigation.

If you need to override this behavior, set the open property explicitly after the widget is ready:

Tips & Tricks

Creating a widget instance manually

You can manually create a widget instance by first including the Widget SDK and then adding the widget element anywhere within the body of your page.

Here’s how to do it:

Assigning notifications

The ChatBotKit Widget can display various types of interactive messages and notifications, which can be dynamically inserted. The widget automatically manages the notification state. Removing a notification from the notifications object will also remove it from the conversation. New notifications will appear in the order they were added to the notifications object.

Consider the following example:

In the example above, we retrieve a list of notifications to present to the user and assign them to the widget once it becomes available via the instancePromise property.

This example will create an effect similar to the one shown in the video below.

Sending messages

You can send messages on behalf of the end-user programmatically. The sendMessage method accepts an options object with text, and optional hidden and respond flags.

To send a hidden message that triggers a bot response without showing anything in the UI, set hidden to true and respond to true. This is useful for sending context or instructions to the bot behind the scenes:

You can also listen for outgoing and incoming messages using the send and receive events:

Pre-filling the message input

Use initiateMessage to pre-fill the message input without sending it. This is handy for suggested prompts or onboarding flows: