ChatBotKit Widget Types

Type definitions for the ChatBotKit widget custom element. This package provides TypeScript types for interacting with the ChatBotKit widget (v2).

What's Included

• ChatBotKitWidgetElementV2: The main widget custom element interface with all available methods and properties
• ChatBotKitGlobalObject: The global window.chatbotkitWidget object interface
• Message: Type for conversation messages
• FunctionDefinition: Type for registering custom functions with the widget
• NotificationDefinition: Type for widget notifications
• Contact: Type for contact information
• Meta: Type for session metadata

Installation

npm install @chatbotkit/widget

Usage

Import the types directly:

import type {
  ChatBotKitWidgetElementV2,
  ChatBotKitGlobalObject,
  FunctionDefinition,
  Message,
} from '@chatbotkit/widget'

// Access the widget instance
const widget = window.chatbotkitWidget.instance

// Or wait for it to be ready
const widget = await window.chatbotkitWidget.instancePromise

// Register custom functions
const myFunction: FunctionDefinition = {
  description: 'Get the current user name',
  parameters: {},
  handler: async () => {
    return 'John Doe'
  },
}

widget.registerFunctions({ getUserName: myFunction })

// Send a message
widget.sendMessage({ text: 'Hello!' })

// Listen to messages
console.log(widget.messages)

Using with the Widget Script

The types augment the global Window interface, so you can access window.chatbotkitWidget with full type safety:

import '@chatbotkit/widget'

// Now window.chatbotkitWidget is typed
window.chatbotkitWidget.instancePromise.then((widget) => {
  widget.open = true
  widget.sendMessage({ text: 'Hello from TypeScript!' })
})

Using with React

For React integration, consider using the @chatbotkit/react package which includes hooks like:

• useWidgetInstance - Access the widget instance
• useWidgetInstanceFunctions - Register functions with the widget
• useWidgetInstanceNotifications - Manage widget notifications

Documentation

For more information about the ChatBotKit widget, visit:

• ChatBotKit Documentation
• Type Documentation

Contributing

Found a bug or wish to contribute? We welcome your input! Please open an issue or submit a pull request on our official GitHub repository.