@chatbotkit/widget

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

Why ChatBotKit?

Build lighter, future-proof AI agents. When you build with ChatBotKit, the heavy lifting happens on our servers-not in your application. This architectural advantage delivers:

• 🪶 Lightweight Agents: Your agents stay lean because complex AI processing, model orchestration, and tool execution happen server-side. Less code in your app means faster load times and simpler maintenance.

• 🛡️ Robust & Streamlined: Server-side processing provides a more reliable experience with built-in error handling, automatic retries, and consistent behavior across all platforms.

• 🔄 Backward & Forward Compatible: As AI technology evolves-new models, new capabilities, new paradigms-your agents automatically benefit. No code changes required on your end.

• 🔮 Future-Proof: Agents you build today will remain capable tomorrow. When we add support for new AI models or capabilities, your existing agents gain those powers without any updates to your codebase.

This means you can focus on building great user experiences while ChatBotKit handles the complexity of the ever-changing AI landscape.

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.