botmesh

A TypeScript framework for messaging bots. Write handlers and conversation flows once and run them on WhatsApp (the unofficial Baileys 7 protocol or the official Meta Cloud API) and Telegram, with experimental providers for Messenger, Instagram, Discord, TikTok, email and more WhatsApp gateways (Evolution API, WPPConnect, Twilio, Gupshup). 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://andresayac.github.io/botmesh/ (English · Español · API reference)

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.

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)

Prerelease. botmesh is not stable yet, and these docs describe the upcoming release. During the beta, add the tag to these commands (npm create botmesh@beta, npm install @botmesh/core@beta …): without it npm installs latest, which can still point to an older alpha. Until the beta is published, npm only has older alphas that differ from the docs in places (built-in texts default to Spanish, pairingCode instead of pairingPhoneNumber, and a scaffolded project needs a .env before npm start). Once @botmesh/core 2.0.0 ships, the commands work as written.

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.

This is a pnpm monorepo with 45 packages: 10 Public, 27 Experimental and 8 Product and internal ones. They are not all equally mature, and the Status column says so plainly:

• Public: published on npm and covered by semver from the stable release on (prerelease builds until then).
• 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.

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.

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 site: https://andresayac.github.io/botmesh/ (English guide, Spanish guide under /es/ and the API reference). Sources in docs/ (English in docs/guide/, Spanish in docs/es/guide/); preview locally with pnpm docs:dev.
• Upgrading from an alpha: Migrating to stable. From v1 (BaileysClass): docs/MIGRATION-v1-to-v2.md.
• Product and engineering roadmap: ROADMAP.md.
• Detailed catalogue of proposals: FEATURES.md.
• Vulnerability reporting policy: SECURITY.md.
• Design and decisions: docs/superpowers/specs/ and docs/superpowers/plans/.

See CONTRIBUTING.md. Relevant changes go in CHANGELOG.md.

MIT © Andres Aya