How to use AI Widget Client-side Functions

This tutorial guides you through the process of leveraging the new Client-side Functions feature in the ChatBotKit AI Widgets. We'll start by embedding the widget and then focus on defining client-side functions to enhance interactivity and functionality.

Embedding the Widget

First, ensure your widget is properly embedded within your web application using the ChatBotKit Widget SDK. You can embed the widget by including the following script tag in your HTML:

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

To pass additional parameters, use data attributes like so:

<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, the SDK initializes but does not instantiate any widgets. To instantiate a widget manually, use the custom HTML tag:

<!-- Embed the Widget SDK -->
<script src="https://static.chatbotkit.com/integrations/widget/v2.js"></script>
<!-- Instantiate a widget within your application -->
<chatbotkit-widget widget="{WIDGET_ID}" open="true"/>

Implementing Client-Side Functions

Once your widget is embedded, you can enhance its capabilities using client-side functions. These functions allow you to provide dynamic data directly to the AI agent. Here’s how you can define a simple client-side function to provide the user's current location to the AI bot:

// Assume userLocation points to the user's current location

const userLocation = ...;

// Obtain an instance of the widget

const instance = chatbotkitWidget.instance; // Alternatively, fetch the instance using another method like getElementById

// Define client-side functions on the instance

instance.functions = {
  getCurrentUserLocation: {
    description: 'Provides the current user location',
    parameters: {},  // This function doesn't require parameters
    result: {
      data: userLocation  // Return the current location data
    }
  }
};

In this example, we've used a static initialization approach where result.data directly holds the value. This function allows the AI to access the user's current location dynamically, ensuring the widget can respond to changes in the user's environment or inputs.

Alternative Implementation Methods

While using the AI Widget SDK is the preferred method for setting up the widget, as it handles most of the configuration for you, there are situations where using the SDK may not be feasible. One common example is when you need to embed the widget directly as a frame, which is often the case with mobile applications.

In the absence of the Widget SDK, you can still assign client-side functions using the AI Widget postMessage protocol. This section discusses this process in detail.

Direct Embedding for Mobile Frameworks

First, embed the AI Widget Frame directly using the following method.

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

This will add the widget frame to the page, allowing you full control over the experience.

Next, declare your client-side functions:

// Assume userLocation points to the user's current location

const userLocation = ...;

// Obtain an instance of the widget

const instance = chatbotkitWidget.instance; // Alternatively, fetch the instance using another method like getElementById

// Define client-side functions on the instance

const functions = {
  getCurrentUserLocation: {
    description: 'Provides the current user location',
    parameters: {},  // This function doesn't require parameters
    result: {
      data: userLocation  // Return the current location data
    }
  }
};

Finally, to assign the functions, send a postMessage event to the frame:

function setFunctions(functions) {
  const frame = document.getElementById('chatbotkit-widget-frame');

  frame.contentWindow.postMessage({
    type: 'setFunctions',
    props: {
      value: Object.entries(functions).map(([name, config]) => {
        return { ...config, name };
      })
    }
  });
}

setFunctions(functions);

This event must be sent after the frame is fully loaded. One way to do this is:

<iframe id="chatbotkit-widget-frame" src="<https://chatbotkit.com/integrations/widget/{WIDGET_ID}/frame>" onload="setFunctions(functions)"></iframe>

By following these steps, you can successfully implement the AI Widget using direct frame embedding and assign client-side functions using the postMessage protocol.

Extending Functionality

You can define additional client-side functions based on your application's needs. Each function can interact with different parts of your application, such as fetching user settings, updating UI elements, or even handling API requests. For more complex functionalities and other forms of function declarations, please refer to the detailed documentation in the Widget Documentation.

By integrating client-side functions, you can make your AI widgets more responsive and intelligent, providing a seamless experience for users interacting with your application.