botmesh
A TypeScript framework for messaging bots. Write handlers and conversation flows once and run them on WhatsApp (the unofficial Baileys 7 protocol, the official Meta Cloud API, the self-hosted Evolution API and WPPConnect gateways, Twilio or Gupshup), Telegram, Facebook Messenger, Instagram DMs, Discord, email, SMS (Twilio) and HighLevel CRM conversations, with an experimental provider for TikTok. Try your bot in the terminal before connecting a phone, test it without a network, and add AI, persistence or multiple replicas when you need them.
Documentation: https://botmesh.afaya.com.co/ (English · Español · API reference)
A bot in 30 seconds
import { Bot, flow } from '@botmesh/core'
import { BaileysProvider } from '@botmesh/baileys'
const bot = new Bot({ provider: new BaileysProvider({ session: 'my-bot' }) })
bot.when('hi', (ctx) => ctx.reply('👋 Hello!'))
bot.use(
flow('signup')
.ask('What is your name?', 'name')
.say((_ctx, c) => `Nice to meet you, ${c.state.name}!`),
)
await bot.start() // scan the QR with WhatsApp → Linked devices
Swap BaileysProvider for TelegramProvider (@botmesh/telegram) or CloudAPIProvider (@botmesh/meta) and the rest stays the same.
Quick start
npm create botmesh my-bot # templates: baileys, telegram, meta, ai, store, support…
cd my-bot && npm install
npm run dev # chat with the bot in the terminal: no phone, no credentials
npm start # connect the real channel
Or add it to an existing project (Node >= 22, ESM-only):
npm install @botmesh/core @botmesh/baileys # WhatsApp (Baileys)
npm install @botmesh/core @botmesh/telegram # Telegram
npm install @botmesh/core @botmesh/meta # WhatsApp Cloud API
npm install @botmesh/ai @anthropic-ai/sdk # + AI (optional; the SDK of the provider you use)
Beta. botmesh is in beta: a plain install gets the beta, and @beta always resolves to the newest one (latest is moved by hand after each publish). The docs describe this beta; once @botmesh/core 2.0.0 ships, the commands stay the same.
The getting started guide walks through the simulator, linking WhatsApp and connecting Telegram step by step.
AI on WhatsApp: since 2026-01-15 the WhatsApp Business Platform terms forbid general-purpose AI assistants (open ChatGPT-style chatbots). AI in the service of the business (support, sales, bookings) is allowed. Details in the AI plugin guide.
Packages
This is a pnpm monorepo with 45 packages: 36 Public, 3 Experimental and 6 Product and internal ones. They are not all equally mature, and the Status column says so plainly:
- Public: published on npm (all 36, as beta versions until the stable release) and covered by semver from the stable release on.
- Experimental: real, tested implementation, but the package is
private. Not published yet and its API may change.
- Product / internal: real, persistent implementation (
private) over any core DurableKv. Per-tenant isolation and compare-and-set in the backend; the API may still change.
| Package | Status | Description |
|---|
| Core | | |
@botmesh/core | Public | Transport-agnostic engine: Bot, IProvider v2, dispatcher, flows/conversations, hooks, plugins, store, testing kit. |
| Transports (channels) | | |
@botmesh/baileys | Public | WhatsApp through Baileys 7 (unofficial, QR or pairing code). |
@botmesh/meta | Public | Official WhatsApp Cloud API (webhook, no ban risk, native buttons/lists/templates). |
@botmesh/telegram | Public | Telegram Bot API (long-poll/webhook, inline keyboards, native polls). |
@botmesh/messenger | Public | Facebook Messenger (Meta Graph Send API, signed webhooks, postback buttons, generic templates). |
@botmesh/instagram | Public | Instagram DMs (Messenger API for Instagram, signed webhooks, quick replies). |
@botmesh/discord | Public | Discord (gateway websocket + REST, slash/components). |
|
Development (in this repo)
pnpm install # install the whole workspace
pnpm build # pnpm -r build → compiles every package
pnpm test # pnpm -r test → full suite
pnpm run docs # TypeDoc + VitePress → documentation site
Per package: pnpm --filter @botmesh/ai test, pnpm --filter @botmesh/core build, and so on.
Examples
| Example | What it shows |
|---|
examples/bakery-ai | AI ordering assistant for a bakery (in English) on WhatsApp, through Baileys (QR) or Twilio (webhook with @botmesh/server). Tools with confirmation, totals computed in code, dedupe, an access list, typed configuration and tests with no network. |
They build and test with the rest of the workspace (pnpm build, pnpm test). Each example ships its own README with the commands to run it.
Documentation
Contributing
See CONTRIBUTING.md. Relevant changes go in CHANGELOG.md.
License
MIT © Andres Aya
