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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗