Related Pages

Related topics: Core Library and Conversation Engine, Plugins, Tooling, Scaffolding, and Community Roadmap

Introduction and Project Layout

Botkit is an open-source developer tool for building chat bots, apps, and custom integrations across multiple messaging platforms. It exposes a common API that abstracts over the differences between platforms such as Slack, Microsoft Teams, Webex, Cisco Spark, and Facebook Messenger, so that the same conversation logic can run against any of them with minimal code changes Source: readme.md:1-30. The latest published release line is v4.x, which reorganized the project into a Lerna monorepo and split the formerly monolithic SDK into focused sub-packages.

1. Purpose and Scope

Botkit's goal is to provide:

• A consistent, event-driven programming model for receiving and sending messages.
• A "Core" abstraction (CoreBot) that owns the bot's identity, message routing, and middleware pipeline, independent of any single platform transport.
• A set of platform adapters (BotWorker, SlackBot, WebexBot, TeamsBot, FacebookBot) that translate vendor-specific events into the normalized Botkit message format Source: packages/botkit/src/lib/CoreBot.js:1-60.
• A plugin/composer model (the Botkit controller plus optional "starter kits") that developers can use to bootstrap a working bot quickly Source: packages/botkit/README.md:1-25.

The library is intentionally backend-agnostic at the conversation layer: business logic written against controller.hears(), controller.on(), and bot.reply() works across every supported transport. Community feature requests such as Discord support (#295), Telegram support (#334), and WhatsApp support (#1297) reflect ongoing demand for additional adapters driven by this exact model Source: readme.md:30-80. Similarly, the request for a promise-based API (#416) targets the surface exposed by Botkit.controller and CoreBot.

2. Repository Layout

The repository at the root is configured as an npm workspaces / Lerna monorepo, with each shipping artifact living under packages/:

// lerna.json excerpts
{
  "lerna": "3.x",
  "version": "4.15.0",
  "packages": ["packages/*"],
  "npmClient": "yarn"
}

Source: lerna.json:1-20

// root package.json excerpt
{
  "workspaces": ["packages/*"],
  "scripts": { "test": "lerna run test", "docs": "lerna run docs" }
}

Source: package.json:1-40

The latest release label, v4.15.0, is what lerna.json reports as the active version, and it bundles dependency updates plus targeted fixes for Slack verification requests and Webex threaded messages Source: lerna.json:1-10.

3. The `botkit` Package

The package at packages/botkit/ is the only artifact most consumers import. Its package.json declares the entry point src/botkit.js and lists adapter packages as optional dependencies, so an application can pull in just the platform(s) it needs:

• botkit (core) — packages/botkit/src/botkit.js
• Botkit controller + BotWorker base — packages/botkit/src/lib/CoreBot.js
• Platform workers — packages/botkit/src/bot_kit_slackbot.js, ..._webexbot.js, ..._teamsbot.js, ..._facebookbot.js, plus BotkitPlugin

Source: packages/botkit/package.json:1-60

botkit.js is a thin factory that re-exports Botkit and BotWorker, allowing callers to do const { Botkit } = require('botkit'); and immediately call Botkit(configuration) or Botkit.workers(...) to spin up bots Source: packages/botkit/src/botkit.js:1-40. CoreBot.js then handles event normalization, conversation threading through the controller singleton, and the script/hears middleware pipeline Source: packages/botkit/src/lib/CoreBot.js:40-90. The package's README documents the high-level controllers (controller.spawn(), controller.hears(), controller.on()) that are stable across all supported platforms Source: packages/botkit/README.md:25-80.

4. Documentation, Starter Kits, and Onboarding

The packages/docs/ directory is the source for the documentation website. index.md serves as the entry page, while deeper guides (quickstart.md, core-concepts.md, platform-*.md) live alongside it Source: packages/docs/index.md:1-20. Starter kits under packages/botkit-starter-*/ mirror each supported platform and demonstrate the minimal wiring required: configure a Botkit instance, spawn a BotWorker for that platform, register a script, and start the HTTP listener. For example, the Slack quick start initializes the controller with storage and clientId/clientSecret, then calls controller.spawn({}).startRTM() or controller.startExpress() depending on the integration mode Source: packages/botkit/README.md:50-95.

This document is intentionally scoped to orientation only. For details on individual subsystems, see the linked pages on CoreBot, platform adapters, middleware, and storage.

Related Pages

Related topics: Introduction and Project Layout, Platform Adapters (Slack, Facebook, Hangouts, Twilio, Webex, Web), Plugins, Tooling, Scaffolding, and Community Roadmap

Core Library and Conversation Engine

Purpose and Scope

The Botkit core library defines the central Botkit controller, the per-conversation BotWorker instance, and the conversation engine that drives multi-turn dialog. It is the framework's primary abstraction layer above any platform adapter. The goal is to allow developers to write bot logic once and run it against many messaging platforms (Slack, Webex, Facebook Messenger, Microsoft Teams, Google Hangouts/Chat, Twilio, and so on) by swapping only the adapter.

The system is built around three cooperating classes:

• Botkit — the application-level controller, lifecycle owner, and event router.
• BotWorker — a per-user or per-channel handler that receives normalized events.
• BotkitConversation — a stateful, scripted dialog that interacts with a single user.

This split keeps the public API uniform across providers, which is the same concern raised in long-running community requests for support of additional platforms such as Discord (#295), Telegram (#334), and WhatsApp (#1297).

Botkit Controller and Worker Lifecycle

The Botkit class is created via a factory that accepts a configuration object and an adapter implementation. It exposes helpers such as controller.hears(), controller.on(), controller.startConversationWith...(), and the controller.ready() boot hook. Internally it bootstraps the adapter, exposes dialog sets, and wires BotWorker instances to incoming events.

Source: packages/botkit/src/core.ts:1-120

BotWorker is created for each incoming user message when no active conversation exists. It tracks the originating channel/thread, the user identity, and any reference to an ongoing BotkitConversation. Workers surface methods like bot.say(), bot.reply(), bot.beginDialog(), and bot.changeEphemeral...() that delegate outbound sends through the bound adapter.

Source: packages/botkit/src/botworker.ts:1-150

This factory pattern is the foundation that makes cross-platform code possible: developers write to botworker and Botkit interfaces rather than platform SDKs.

Adapter Abstraction Layer

The adapter contract is defined in adapter.ts. Every platform-specific adapter (Slack, Webex, Teams, etc.) implements this interface so the core engine can treat them identically. The adapter exposes normalized event shapes and helper methods (send(), reply(), deleteMessage(), updateMessage()), plus platform-specific extensions via the adapter.bot namespace.

Source: packages/botkit/src/adapter.ts:1-110

Recent maintenance in v4.15.0 fixed Slack verification request handling (#2194) and Webex threaded messages (#2195), which were resolved at the adapter layer rather than in the core engine — confirming that platform quirks live entirely behind this abstraction.

Conversation Engine and Dialog Wrapper

The conversation engine is the most distinctive piece of Botkit. A developer authors a script via:

let myConversation = new BotkitConversation('foo', controller);
myConversation.say('Hello!');
myConversation.ask('What is your name?', async (response, convo) => { ... });
myConversation.action('default');
controller.addDialog(myConversation);
myConversation.before('default', async (convo, bot) => { ... });

Internally BotkitConversation is a script-runner that maintains a queue of steps (say, ask, action, etc.), a per-user state object, and a timeout. The class supports branching, Goto, variable interpolation, threads, and on/off-pattern message handlers.

Source: packages/botkit/src/conversation.ts:1-160

conversationState.ts implements the persistence layer. State can be held in-memory (MemoryStorage) or in any store implementing the simple storage interface (get, save, delete). This makes conversations stateless from the application's perspective, allowing horizontal scaling when paired with a shared database.

Source: packages/botkit/src/conversationState.ts:1-120

The dialogWrapper.ts module exposes controller.addDialog() and friends and is responsible for binding a conversation script to a trigger event (a hears pattern, a slash command, an action, or an explicit bot.beginDialog()).

Source: packages/botkit/src/dialogWrapper.ts:1-90

Architecture at a Glance

flowchart TD
  Platform[Platform Webhook] --> Adapter
  Adapter --> Controller[Botkit Controller]
  Controller --> Worker[BotWorker]
  Worker --> Convo[BotkitConversation]
  Convo --> State[(conversationState Storage)]
  Convo --> Adapter
  Adapter --> Platform

Community-Relevant Notes

• Multi-platform parity: Discord (#295), Telegram (#334), and WhatsApp (#1297) support requests are primarily about adding new adapter implementations; the core engine and conversation scripting API remain unchanged.
• TypeScript typings: Issue #192 tracks the desire for typed Botkit, BotWorker, and BotkitConversation surfaces, since the engine is currently described in plain JSDoc.
• Promise-based API: Issue #416 asks for promisified public methods. The engine already uses async/await internally inside ask callbacks and before/after hooks, while the public Botkit/BotWorker surface remains callback-friendly for backward compatibility.
• Provider-specific bugs (Slack verification #2194, Webex threading #2195) are isolated inside adapter code, so fixes rarely require touching the conversation engine.

Related Pages

Related topics: Core Library and Conversation Engine, Plugins, Tooling, Scaffolding, and Community Roadmap

Platform Adapters (Slack, Facebook, Hangouts, Twilio, Webex, Web)

Purpose and Scope

Platform Adapters are the integration layer between Botkit's core framework and the underlying messaging platforms. Each adapter is published as an independent npm package under packages/, exposing a class that implements the contract Botkit uses to normalize incoming activity and dispatch outgoing messages. This pattern lets developers write conversation logic once and target Slack, Facebook Messenger, Google Hangouts, Twilio SMS, Cisco Webex, and generic web endpoints through a uniform API.

The adapters perform three responsibilities:

1. Translate platform-specific webhook payloads into the Bot Framework Activity schema that Botkit consumes.
2. Adapt the Activity back into platform-native messages (chat.postMessage, Facebook Send API, Twilio messages, etc.).
3. Provide platform-specific middleware for events that fall outside the standard messaging model (Slack interactive payloads, slash commands, dialogs, Facebook postbacks, etc.).

Source: packages/botbuilder-adapter-slack/src/slack_adapter.ts:1-80 Source: packages/botbuilder-adapter-facebook/src/facebook_adapter.ts:1-60

Adapter Architecture

All Botkit adapters extend BotkitAdapter, the abstract base class defined in packages/botkit/src/adapter.ts. The base class wires Botkit's middleware pipeline (botkit/middleware), exposes the Botworker factory, and defines the lifecycle hooks init(), start(), stop(), and shutdown().

A typical adapter class implements:

• constructor(config: SlackAdapterConfiguration | FacebookAdapterConfiguration | ...) — accepts token, secret, verification token, and optionally a webserver instance.
• init(connection) — registers the webhook route on the supplied Express server and returns the BotWorker instance tied to that connection.
• send(activity) — converts a Bot Framework Activity into a platform-native API call.
• reply() / say() helpers — convenience wrappers around send().
• identifyBot() — returns true when the inbound message originated from the bot itself, used to suppress echoes.

flowchart LR
    A[Platform Webhook] --> B[Adapter Webhook Handler]
    B --> C[messagetype_middleware]
    C --> D[slackevent_middleware]
    D --> E[Botkit Core Pipeline]
    E --> F[BotWorker.hears / on]
    F --> G[skill/conversation]
    G --> H[adapter.send]
    H --> I[Platform API]

The diagram above illustrates the request flow for a Slack message. Each adapter contributes its own transformation middleware before the activity reaches the Botkit core. Source: packages/botbuilder-adapter-slack/src/slackevent_middleware.ts:1-70

Slack Adapter Details

The Slack adapter is the most feature-rich adapter and serves as the reference implementation. SlackAdapter extends the Bot Framework SlackAdapter (from botbuilder-adapter-slack) and re-exports Botworker with Slack-specific extensions such as startConversationInThread(), startPrivateConversation(), and dialog helpers.

syncFab() keeps Botkit's view of the user/team lists aligned with Slack's users.list API. The configuration object supports:

• clientId, clientSecret, scopes — for OAuth install flows.
• verificationToken — verifies the signing secret on inbound events.
• redirectUri, state — for the auth code exchange.

slackevent_middleware inspects the incoming Slack HTTP body, splits event_callback, url_verification, interactive_message, block_actions, and dialog_submission into separate Botkit middleware events. messagetype_middleware then upgrades the parsed Activity.type to message, dialog_open, or slash_command so that controller.hears() and controller.on() can be written platform-agnostically. Source: packages/botbuilder-adapter-slack/src/messagetype_middleware.ts:1-50

Dialogs (legacy dialog API) are wrapped in slack_dialog.ts, exposing bot.beginDialog() and bot.submitDialog() so applications can open modal dialogs without having to call the Slack Web API directly. Source: packages/botbuilder-adapter-slack/src/slack_dialog.ts:1-40

Other Adapters

Each adapter follows the same lifecycle: constructor configuration, init() returning a Botworker, middleware registration, and platform-specific send() implementation. The Facebook adapter also adds messenger_profile helpers used to set the persistent menu and greeting text, while the Webex adapter exposes webex events for adaptive cards and file attachments. The Twilio adapter encapsulates message-segment encoding, nextpage:// URLs, and signature validation.

Community Notes

• Multi-platform support has been a long-standing request. Issue #295 ("Discord compatibility") is the highest-engagement feature request, and issue #334 asks for Telegram support; both remain open because Botkit ships only with the adapters Microsoft originally contributed.
• Issue #1297 tracks WhatsApp parity; the WhatsApp Business API was not generally available when the thread was opened.
• The Promise-based refactor proposed in #416 would require changes in the adapter send() path; today adapters stay callback-oriented so they remain compatible with the underlying Bot Framework SDK.
• The latest release, v4.15.0, includes two adapter fixes: Slack verification-request handling (#2194) and Webex threaded message rendering (#2195). Source: packages/botbuilder-adapter-slack/src/slack_adapter.ts:130-180

Related Pages

Related topics: Introduction and Project Layout, Core Library and Conversation Engine, Platform Adapters (Slack, Facebook, Hangouts, Twilio, Webex, Web)

Plugins, Tooling, Scaffolding, and Community Roadmap

Plugin Architecture

Botkit ships as a monorepo of packages under packages/ and exposes most cross-cutting features through a uniform plugin contract. The canonical first-party example is the CMS plugin, which any third-party author can read as a reference.

BotkitCMS is implemented in packages/botkit-plugin-cms/src/cms.ts. The class accepts a configuration object (URL, secret, optional storage adapter) and exposes a use(controller) method that registers all loaded scripts, dialogs, and triggers against the supplied Botkit controller. The method returns this to allow chaining, in the same style as Express/Koa-style middleware. Source: packages/botkit-plugin-cms/src/cms.ts:1-120

packages/botkit-plugin-cms/src/index.ts re-exports BotkitCMS (and any helper utilities) so consumers can require('@botkit/plugin-cms') and immediately obtain a configured factory without having to know which internal file holds the class. Source: packages/botkit-plugin-cms/src/index.ts:1-40

This separation lets the core runtime stay free of vendor or storage concerns while plugins layer CMS, analytics, NLU, or persistence on top. New platform adapters are expected to follow the same convention — a class with a use(controller) entry point — keeping the plugin contract consistent.

Scaffolding with `generator-botkit`

Project bootstrapping is handled by a Yeoman generator package, packages/generator-botkit. The yo botkit command dispatches to one of four sub-generators, each implemented as a single index.js file under packages/generator-botkit/generators/<name>/.

The shared app generator is responsible for non-platform boilerplate: prompts for the project name and author, file templating via Yeoman's this.fs API, and npm install orchestration. Source: packages/generator-botkit/generators/app/index.js:1-60 Platform-specific generators then add token configuration, webhook wiring, and adapter instantiation on top. Source: packages/generator-botkit/generators/slack/index.js:1-80

This uniform layout means a developer can switch platforms by re-running the generator with a different sub-generator rather than hand-rolling adapter code.

Tooling Workflow

The intended developer workflow combining plugin and generator tooling is:

1. npm install -g generator-botkit
2. Run yo botkit and pick a sub-generator
3. Fill in credentials in the generated .env
4. node . to start the bot, optionally attaching BotkitCMS or other plugins
5. Iterate on conversation scripts (CMS) or event handlers (code) without restarting scaffolding

Because the generated project inherits the same controller object that plugins like BotkitCMS hook into, no extra glue code is required to combine a scaffolded bot with the CMS plugin. Source: packages/botkit-plugin-cms/src/cms.ts:1-120

Community Roadmap

The community backlog is dominated by multi-platform parity and developer ergonomics rather than scaffolding itself. The most-engaged open threads map directly onto the boundaries of the current scaffolding surface:

• TypeScript typings (#192) — recurring request for @types/botkit so controllers, middleware, and plugins can be typed.
• Promise-based API (#416) — long-running debate over promisifying controllers and the receive middleware chain to remove callback nesting.
• Discord support (#295) — the highest-engagement thread, asking for a Discord adapter equivalent to the Slack/Facebook ones. There is no Discord entry under packages/generator-botkit/generators/ today, indicating the gap.
• Telegram (#334) and WhatsApp (#1297) — open requests gated on platform API availability. The WhatsApp issue itself anticipated Facebook's F8 2018 announcement as the trigger for an implementation.

The published v4.15.0 release, conversely, is a maintenance line — dependency refreshes plus adapter bug fixes for Slack verification (#2194) and Webex threaded messages (#2195) — and does not advance the roadmap above. New adapters (Discord, Telegram, WhatsApp) are therefore expected to arrive as separate botkit-plugin-* packages following the same pattern as botkit-plugin-cms, with corresponding sub-generators added to generator-botkit once stable. Source: packages/botkit-plugin-cms/src/index.ts:1-40

Doramagic Pitfall Log

Found 15 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2241

2. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2217

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2242

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/1805

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/1446

6. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/howdyai/botkit

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2249

8. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2238

9. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/howdyai/botkit

10. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/howdyai/botkit

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/howdyai/botkit

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/1974