botmesh

A TypeScript framework for messaging bots. Write handlers and conversation flows once, run them on WhatsApp (Baileys or the official Cloud API) and Telegram, and try them in your terminal without a phone.

One bot, every chat channel

Get started

Your first bot

API reference

Transport-agnostic

One engine, many providers: @botmesh/baileys (WhatsApp Web), @botmesh/meta (official WhatsApp Cloud API), @botmesh/telegram, @botmesh/messenger, @botmesh/instagram, Discord, Twilio, email and more. Switching channels changes one line.

Conversation flows

flow(‘signup’).ask().choose().say() compiles to a real async conversation with validation, retries, branching and timeouts. Persistent flows survive a restart.

Try it without a phone

npx botmesh dev bot.js chats with your bot in the terminal, with hot reload and no account, number or ban risk.

Testable

createTestBot and MockProvider run your flows in unit tests with no network. Golden transcripts catch regressions in whole conversations.

AI when you need it

@botmesh/ai answers with Anthropic, OpenAI, Gemini, Ollama or OpenAI-compatible models, calls your tools with confirmation and remembers each user.

Hooks and plugins

before / after / onError middleware on every message and send, and reusable plugins such as the built-in slash commands.

Pluggable stores

MemoryStore by default; SQLite, Redis, PostgreSQL, MySQL and MongoDB stores for persistence, or your own IStore.

Ready for production

Inbound dedupe on by default and an anti-ban rate limiter on Baileys; opt-in durable processing, multiple replicas, a durable scheduler and OpenTelemetry traces.

Typed throughout

ESM packages written in TypeScript: autocomplete and type checking on every handler, flow state and plugin. Plain JavaScript works too.

A bot in a few lines

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 or CloudAPIProvider and the rest of the code stays the same.

Start in five minutes

npm create botmesh my-bot
cd my-bot && npm install
npm run dev        # chat with it in the terminal
npm start          # connect WhatsApp or Telegram

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). Getting started walks through every step, including setting up a project by hand.