# https://github.com/howdyai/botkit Project Manual

Generated at: 2026-07-16 10:52:28 UTC

## Table of Contents

- [Introduction and Project Layout](#page-1)
- [Core Library and Conversation Engine](#page-2)
- [Platform Adapters (Slack, Facebook, Hangouts, Twilio, Webex, Web)](#page-3)
- [Plugins, Tooling, Scaffolding, and Community Roadmap](#page-4)

<a id='page-1'></a>

## Introduction and Project Layout

### Related Pages

Related topics: [Core Library and Conversation Engine](#page-2), [Plugins, Tooling, Scaffolding, and Community Roadmap](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [readme.md](https://github.com/howdyai/botkit/blob/main/readme.md)
- [package.json](https://github.com/howdyai/botkit/blob/main/package.json)
- [lerna.json](https://github.com/howdyai/botkit/blob/main/lerna.json)
- [packages/botkit/README.md](https://github.com/howdyai/botkit/blob/main/packages/botkit/README.md)
- [packages/botkit/package.json](https://github.com/howdyai/botkit/blob/main/packages/botkit/package.json)
- [packages/docs/index.md](https://github.com/howdyai/botkit/blob/main/packages/docs/index.md)
- [packages/botkit/src/botkit.js](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/botkit.js)
- [packages/botkit/src/lib/CoreBot.js](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/lib/CoreBot.js)
</details>

# 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/`:

| Top-level Path | Role |
| --- | --- |
| `readme.md` | Project-level landing page with quick-start, platform instructions, and links to docs. |
| `package.json` | Root manifest; declares workspaces and top-level scripts (`test`, `docs`). |
| `lerna.json` | Lerna configuration that pins the package versioning strategy and bootstrap behavior. |
| `packages/botkit/` | The main npm package, `botkit`. Contains `src/` with `botkit.js`, `lib/CoreBot.js`, and adapters. |
| `packages/botkit-starter-*` | Starter kits (Slack, Webex, Facebook, Teams, etc.) that show end-to-end usage. |
| `packages/docs/` | Source for the docs site (`index.md` is the landing page). |

```json
// lerna.json excerpts
{
  "lerna": "3.x",
  "version": "4.15.0",
  "packages": ["packages/*"],
  "npmClient": "yarn"
}
```
`Source: [lerna.json:1-20]()`

```json
// 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.

---

<a id='page-2'></a>

## Core Library and Conversation Engine

### Related Pages

Related topics: [Introduction and Project Layout](#page-1), [Platform Adapters (Slack, Facebook, Hangouts, Twilio, Webex, Web)](#page-3), [Plugins, Tooling, Scaffolding, and Community Roadmap](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/botkit/src/core.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/core.ts)
- [packages/botkit/src/botworker.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/botworker.ts)
- [packages/botkit/src/adapter.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/adapter.ts)
- [packages/botkit/src/conversation.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/conversation.ts)
- [packages/botkit/src/conversationState.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/conversationState.ts)
- [packages/botkit/src/dialogWrapper.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit/src/dialogWrapper.ts)
</details>

# 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:

```js
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

| Layer | Class / Module | Responsibility |
|---|---|---|
| Application | `Botkit` | Lifecycle, listener registration, dialog registry |
| Per-User | `BotWorker` | Sends messages, holds references to active dialog |
| Platform | `Adapter` | Normalizes platform events, delivers outbound messages |
| Dialog | `BotkitConversation` + `dialogWrapper` | Scripted multi-turn dialog flow |
| Storage | `conversationState` | Persists conversation variables across restarts |

```mermaid
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.

---

<a id='page-3'></a>

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

### Related Pages

Related topics: [Core Library and Conversation Engine](#page-2), [Plugins, Tooling, Scaffolding, and Community Roadmap](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/botbuilder-adapter-slack/src/slack_adapter.ts](https://github.com/howdyai/botkit/blob/main/packages/botbuilder-adapter-slack/src/slack_adapter.ts)
- [packages/botbuilder-adapter-slack/src/slackevent_middleware.ts](https://github.com/howdyai/botkit/blob/main/packages/botbuilder-adapter-slack/src/slackevent_middleware.ts)
- [packages/botbuilder-adapter-slack/src/messagetype_middleware.ts](https://github.com/howdyai/botkit/blob/main/packages/botbuilder-adapter-slack/src/messagetype_middleware.ts)
- [packages/botbuilder-adapter-slack/src/slack_dialog.ts](https://github.com/howdyai/botkit/blob/main/packages/botbuilder-adapter-slack/src/slack_dialog.ts)
- [packages/botbuilder-adapter-slack/src/botworker.ts](https://github.com/howdyai/botkit/blob/main/packages/botbuilder-adapter-slack/src/botworker.ts)
- [packages/botbuilder-adapter-facebook/src/facebook_adapter.ts](https://github.com/howdyai/botkit/blob/main/packages/botbuilder-adapter-facebook/src/facebook_adapter.ts)
</details>

# 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.

```mermaid
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

| Adapter | Package | Source-of-truth file |
| --- | --- | --- |
| Facebook Messenger | `botbuilder-adapter-facebook` | `packages/botbuilder-adapter-facebook/src/facebook_adapter.ts` |
| Google Hangouts Chat | `botbuilder-adapter-hangouts` | `packages/botbuilder-adapter-hangouts/src/hangouts_adapter.ts` |
| Twilio SMS | `botbuilder-adapter-twilio-sms` | `packages/botbuilder-adapter-twilio-sms/src/twilio_adapter.ts` |
| Cisco Webex Teams | `botbuilder-adapter-webex` | `packages/botbuilder-adapter-webex/src/webex_adapter.ts` |
| Generic Web (Botkit Studio) | `botbuilder-adapter-web` | `packages/botbuilder-adapter-web/src/web_adapter.ts` |

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]()

---

<a id='page-4'></a>

## Plugins, Tooling, Scaffolding, and Community Roadmap

### Related Pages

Related topics: [Introduction and Project Layout](#page-1), [Core Library and Conversation Engine](#page-2), [Platform Adapters (Slack, Facebook, Hangouts, Twilio, Webex, Web)](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/botkit-plugin-cms/src/cms.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit-plugin-cms/src/cms.ts)
- [packages/botkit-plugin-cms/src/index.ts](https://github.com/howdyai/botkit/blob/main/packages/botkit-plugin-cms/src/index.ts)
- [packages/generator-botkit/generators/app/index.js](https://github.com/howdyai/botkit/blob/main/packages/generator-botkit/generators/app/index.js)
- [packages/generator-botkit/generators/slack/index.js](https://github.com/howdyai/botkit/blob/main/packages/generator-botkit/generators/slack/index.js)
- [packages/generator-botkit/generators/facebook/index.js](https://github.com/howdyai/botkit/blob/main/packages/generator-botkit/generators/facebook/index.js)
- [packages/generator-botkit/generators/web/index.js](https://github.com/howdyai/botkit/blob/main/packages/generator-botkit/generators/web/index.js)
</details>

# 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>/`.

| Sub-generator | Entry file | Produces |
|---|---|---|
| `app` | `packages/generator-botkit/generators/app/index.js` | Platform-neutral core with `package.json`, `.env`, `.gitignore`, entry file and README |
| `slack` | `packages/generator-botkit/generators/slack/index.js` | Slack app wired through the Bolt-style adapter and signing-secret verification |
| `facebook` | `packages/generator-botkit/generators/facebook/index.js` | Facebook Messenger bot using Botkit's FB adapter and webhook setup |
| `web` | `packages/generator-botkit/generators/web/index.js` | Browser widget bot served over WebSocket/HTTP |

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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: howdyai/botkit

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2241

## 2. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2217

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2242

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/1805

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/1446

## 6. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/howdyai/botkit

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2249

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2238

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/howdyai/botkit

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/howdyai/botkit

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/howdyai/botkit

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/1974

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: community_evidence:github | https://github.com/howdyai/botkit/issues/2246

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/howdyai/botkit

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/howdyai/botkit

<!-- canonical_name: howdyai/botkit; human_manual_source: deepwiki_human_wiki -->