←back to docs

Widget SDK

The Widget SDK allows developers to easily initialize and configure ChatBotKit AI Widgets. This guide provides detailed instructions for embedding, utilizing the global object, and managing widget properties and events.

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:

<!-- embed the widget sdk and instantiate the widget -->
<script src="https://static.chatbotkit.com/integrations/widget/v2.js" data-widget="{WIDGET_ID}"></script>

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

<!-- embed the widget sdk and instantiate the widget with additional properties -->
<script src="https://static.chatbotkit.com/integrations/widget/v2.js" data-widget="{WIDGET_ID}" data-open="true"></script>

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:

<!-- 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"/>

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.

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 - A boolean property that indicates whether the widget is ready.
  • messages: {id: string, type: string, text: string}[] - 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,{text: string}> - 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,{description: string, properties: object, result: { data?: any, handler?: (...args: any) => any }}> - An object containing function definitions available to the AI bot. You can modify these functions by directly assigning new values to this property.
  • meta: Record<string,any> - 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 of the ChatBotKitWidget class.

Methods

  • hide() -> void - A convenience method to hide the widget by changing its visibility. This method does not toggle the open state of the widget.
  • show() -> void -A convenience method to show the widget by changing its visibility. This method does not toggle the open state of the widget.
  • restartConversation() -> void - Restarts the current conversation. Once invoked, this method will clear all messages and reset the conversation session
  • sendMessage(message: string) -> void - Creates a new text message on behalf of the end-user. This has the same effect as if the end-user had typed the message themselves.
  • postMessage(message: object) -> void - Sends a message to the widget frame using the standard cross-window postMessage message protocol.

Events

  • ready, (event: { target: ChatBotKitWidget }) - The event is triggered when the widget is ready.
  • send, (event: { target: ChatBotKitWidget, data: Message}) - The event is triggered when a message is sent by the end-user or through the sendMessage function.
  • receive, (event: { target: ChatBotKitWidget, data: Message}) - The event is triggered when a message is received from the bot.”

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:

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

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:

// a placeholder function to retrieve the available notifications from the applicaion
  
async function getNotifications() {
  // artificial delay to simulate network fetch
    
  await new Promise((resolve) => {
    setTimeout(() => resolve(), 1000)
  })

  // return available notifications
  
  const uniqueNotificationId = Math.random().toString(32).slice(2)
    
  return {
    [uniqueNotificationId]: {
      text: 'Hi Sara, your device has been offline for 12 hours\n\n[What is the current status of my device]() [How can I get my device back online]()'
    }
  }
}

// a helper function to setup the notifications
  
async function setupNotifications() {
  const notifications = await getNotifications()

  const instance = await window.chatbotkitWidget.instancePromise

  instance.notifications = notifications
}

setupNotifications()

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.

See Preview

widgetSDK