or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bot-controller.mdbot-worker.mdconversations.mddialog-wrapper.mdindex.mdmessage-handling.mdteams-integration.mdtesting.md
tile.json

tessl/npm-botkit

Building blocks for creating conversational bots and chatbot applications across multiple messaging platforms

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/botkit@4.15.x

To install, run

npx @tessl/cli install tessl/npm-botkit@4.15.0

index.mddocs/

Botkit

Botkit is an open source developer tool for building chat bots, apps and custom integrations for major messaging platforms. It serves as a comprehensive framework that provides building blocks for creating conversational interfaces and chatbots across multiple platforms including Slack, Facebook Messenger, Webex Teams, Google Hangouts, Twilio SMS, and web-based chat interfaces.

Package Information

  • Package Name: botkit
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install botkit

Core Imports

import { 
  Botkit, 
  BotkitMessage, 
  BotWorker, 
  BotkitConversation,
  BotkitDialogWrapper,
  TeamsBotWorker,
  TeamsInvokeMiddleware,
  BotkitTestClient
} from "botkit";

For CommonJS:

const { 
  Botkit, 
  BotkitMessage, 
  BotWorker, 
  BotkitConversation,
  BotkitDialogWrapper,
  TeamsBotWorker,
  TeamsInvokeMiddleware,
  BotkitTestClient
} = require("botkit");

Basic Usage

import { Botkit } from "botkit";

// Create a bot controller
const controller = new Botkit({
  webhook_uri: "/api/messages",
});

// Listen for messages
controller.hears("hello", "message", async (bot, message) => {
  await bot.reply(message, "Hello there!");
});

// Handle events
controller.on("conversationUpdate", async (bot, message) => {
  await bot.reply(message, "Welcome to the conversation!");
});

// Create and use conversations
const convo = new BotkitConversation("greeting", controller);
convo.say("Hi! What's your name?");
convo.ask("Please tell me your name:", async (response, convo, bot) => {
  await bot.say(`Nice to meet you, ${response}!`);
}, { key: "name" });

controller.addDialog(convo);

// Start the conversation
controller.hears("start", "message", async (bot, message) => {
  await bot.beginDialog("greeting");
});

Architecture

Botkit is built around several key components:

  • Controller: The main Botkit class that manages the bot's lifecycle, message routing, and dialog system
  • BotWorker: Individual bot instances that handle message sending, dialog management, and platform-specific operations
  • Conversations: Dialog system for creating multi-turn conversations with users
  • Middleware: Plugin system for extending functionality at different stages of message processing
  • Adapters: Platform-specific connectors for different messaging services
  • Storage: Persistent state management for conversations and user data

Capabilities

Bot Controller

Core bot management functionality including initialization, configuration, message routing, and plugin system. The main entry point for creating and managing conversational applications.

class Botkit {
  constructor(config: BotkitConfiguration);
  version: string;
  middleware: MiddlewareEndpoints;
  storage: Storage;
  webserver: any;
  adapter: any;
  dialogSet: DialogSet;
}

interface BotkitConfiguration {
  webhook_uri?: string;
  dialogStateProperty?: string;
  adapter?: any;
  adapterConfig?: { [key: string]: any };
  webserver?: any;
  webserver_middlewares?: any[];
  storage?: Storage;
  disable_webserver?: boolean;
  disable_console?: boolean;
  jsonLimit?: string;
  urlEncodedLimit?: string;
}

Bot Controller

Message Handling

Event-driven message processing system for listening to keywords, patterns, and platform events. Supports pattern matching, interrupts, and custom event handling.

interface BotkitMessage {
  type: string;
  text?: string;
  value?: string;
  user: string;
  channel: string;
  reference: ConversationReference;
  incoming_message: Activity;
  [key: string]: any;
}

interface BotkitHandler {
  (bot: BotWorker, message: BotkitMessage): Promise<any>;
}

Message Handling

Bot Worker

Individual bot instances that handle message sending, dialog management, and context switching. Each worker represents a bot's interaction with a specific user or conversation.

class BotWorker {
  constructor(controller: Botkit, config: any);
  controller: Botkit;
  say(message: Partial<BotkitMessage> | string): Promise<any>;
  reply(src: Partial<BotkitMessage>, resp: Partial<BotkitMessage> | string): Promise<any>;
  beginDialog(id: string, options?: any): Promise<void>;
  changeContext(reference: Partial<ConversationReference>): Promise<BotWorker>;
}

Bot Worker

Conversations & Dialogs

Multi-turn conversation system with thread management, conditional logic, and state persistence. Supports complex dialog flows with branching, variable collection, and user input validation.

class BotkitConversation<O extends object = {}> extends Dialog<O> {
  constructor(dialogId: string, controller: Botkit);
  script: any;
  say(message: Partial<BotkitMessageTemplate> | string): BotkitConversation;
  ask(message: Partial<BotkitMessageTemplate> | string, handlers: BotkitConvoHandler | BotkitConvoTrigger[], key: {key: string} | string | null): BotkitConversation;
  addAction(action: string, thread_name?: string): BotkitConversation;
  before(thread_name: string, handler: (convo: BotkitDialogWrapper, bot: BotWorker) => Promise<any>): void;
  after(handler: (results: any, bot: BotWorker) => void): void;
}

interface BotkitMessageTemplate {
  text: ((template: any, vars: any) => string) | string[];
  action?: string;
  execute?: { script: string; thread?: string; };
  quick_replies?: ((template: any, vars: any) => any[]) | any[];
  attachments?: ((template: any, vars: any) => any[]) | any[];
  blocks?: ((template: any, vars: any) => any[]) | any[];
  attachment?: ((template: any, vars: any) => any) | any;
  attachmentLayout?: string;
  channelData?: any;
  collect: { key?: string; options?: BotkitConvoTrigger[]; };
}

Conversations & Dialogs

Dialog Wrapper

Simplified interface for controlling conversation flow and managing variables during dialog execution. Provides easy access to thread navigation and state management.

class BotkitDialogWrapper {
  vars: { [key: string]: any };
  gotoThread(thread: string): Promise<void>;
  repeat(): Promise<void>;
  stop(): Promise<void>;
  setVar(key: string, val: any): void;
}

Dialog Wrapper

Microsoft Teams Integration

Specialized functionality for Microsoft Teams including task modules, channel management, and Teams-specific event handling.

class TeamsBotWorker extends BotWorker {
  teams: TeamsInfo;
  replyWithTaskInfo(message: BotkitMessage, taskInfo: any): Promise<any>;
}

class TeamsInvokeMiddleware extends MiddlewareSet {
  onTurn(context: TurnContext, next: () => Promise<any>): Promise<void>;
}

class BotkitBotFrameworkAdapter extends BotFrameworkAdapter {
  botkit_worker: TeamsBotWorker;
  getChannels(context: TurnContext): Promise<ChannelInfo[]>;
}

Microsoft Teams Integration

Testing

Comprehensive testing utilities for dialog testing, conversation simulation, and bot behavior validation.

class BotkitTestClient {
  constructor(channelId: string, bot: Botkit, dialogToTest: string | string[], initialDialogOptions?: any, middlewares?: Middleware[], conversationState?: ConversationState);
  dialogTurnResult: DialogTurnResult;
  conversationState: ConversationState;
  sendActivity(activity: Partial<Activity> | string): Promise<any>;
  getNextReply(): Partial<Activity>;
}

Testing

Types

interface MiddlewareEndpoints {
  spawn: Ware;
  ingest: Ware;
  send: Ware;
  receive: Ware;
  interpret: Ware;
}

interface BotkitPlugin {
  name: string;
  middlewares?: { [key: string]: any[]; };
  init?: (botkit: Botkit) => void;
  [key: string]: any;
}

interface BotkitConvoHandler {
  (answer: string, convo: BotkitDialogWrapper, bot: BotWorker, message: BotkitMessage): Promise<any>;
}

interface BotkitConvoTrigger {
  type?: string;
  pattern?: string | RegExp;
  handler: BotkitConvoHandler;
  default?: boolean;
}

interface BotkitTrigger {
  type: string;
  pattern: string | RegExp | { (message: BotkitMessage): Promise<boolean> };
  handler: BotkitHandler;
}

interface BotkitConversationStep {
  index: number;
  thread: string;
  threadLength: number;
  state: any;
  options: any;
  reason: DialogReason;
  result: any;
  values: any;
  next: (stepResult) => Promise<any>;
}

/** Internal class for advanced conversation state management (typically used automatically) */
class BotkitConversationState extends ConversationState {
  getStorageKey(context: TurnContext): string | undefined;
}