A modern, transport-agnostic framework for messaging bots: declarative flows to get going in 30 seconds, an async conversation runtime when you need full control, and a multi-provider AI plugin. Two WhatsApp transports —Baileys 7 (unofficial) and the official Meta Cloud API— behind the same IProvider, plus Telegram and experimental channels (Messenger, Instagram, Discord, TikTok, email, and WhatsApp through Evolution API, WPPConnect, Twilio or Gupshup). pnpm monorepo in alpha: the packages are on npm under the alpha dist-tag (pnpm add @botmesh/core@alpha).
The monorepo has 45 packages: 10 Alpha (publishable), 27 Experimental and 8 Product and infrastructure ones. They are not all equally mature, and the Status column says so plainly:
- Alpha: published on npm under the
alphadist-tag (install with@alpha; there is nolatestyet). - 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 coreDurableKv. Per-tenant isolation and compare-and-set in the backend; the API may change until the alpha ships.
| Package | Status | Description |
|---|---|---|
| Core | ||
@botmesh/core |
Alpha | Transport-agnostic engine: Bot, IProvider v2, dispatcher, flows/conversations, hooks, plugins, store, testing kit. |
| Transports (channels) | ||
@botmesh/baileys |
Alpha | WhatsApp through Baileys 7 (unofficial, QR or pairing code). |
@botmesh/meta |
Alpha | Official WhatsApp Cloud API (webhook, no ban risk, native buttons/lists/templates). |
@botmesh/telegram |
Alpha | Telegram Bot API (long-poll/webhook, inline keyboards, native polls). |
@botmesh/messenger |
Experimental | Facebook Messenger (Meta Graph, quick replies/templates). |
@botmesh/instagram |
Experimental | Instagram DM (Meta Graph, quick replies). |
@botmesh/discord |
Experimental | Discord (gateway websocket + REST, slash/components). |
@botmesh/evolution |
Experimental | WhatsApp through Evolution API (self-hosted REST gateway, signed webhook). |
@botmesh/wppconnect |
Experimental | WhatsApp through WPPConnect Server (REST + token webhook). |
@botmesh/twilio |
Experimental | WhatsApp and SMS through Twilio Programmable Messaging (X-Twilio-Signature webhooks). |
@botmesh/gupshup |
Experimental | WhatsApp through Gupshup (API v1 + v2 callbacks). |
@botmesh/gohighlevel |
Experimental | GoHighLevel / LeadConnector (Conversations API + signed InboundMessage webhooks). |
@botmesh/email |
Experimental | Email: inbound IMAP IDLE + outbound SMTP, threading, loop and bounce protection. |
@botmesh/tiktok |
Experimental | TikTok API for Business: DMs (Business Messaging) and replies to comments on your own videos. |
| Stores (persistence) | ||
@botmesh/sqlite-store |
Alpha | SQLite (better-sqlite3, WAL). |
@botmesh/redis-store |
Alpha | Distributed Redis (+ multi-replica lock). |
@botmesh/mongo-store |
Experimental | MongoDB. |
@botmesh/postgres-store |
Experimental | PostgreSQL (pg). |
@botmesh/mysql-store |
Experimental | MySQL/MariaDB (mysql2). |
| Plugins | ||
@botmesh/ai |
Alpha | AI: Anthropic/OpenAI/Ollama/Gemini + 9 OpenAI-compatible presets (DeepSeek/Qwen/GLM/Kimi/Groq/…), auto-reply, tool calling with confirmation, per-user long-term memory and RAG. See the WhatsApp AI policy. |
@botmesh/nlu |
Experimental | Local intents/NLU (define/match + whenIntent), no external services. |
@botmesh/manager |
Experimental | Multi-bot orchestrator (registry, lifecycle) + dependency-free HTTP API (control plane /v1 with API keys). |
@botmesh/otel |
Experimental | OpenTelemetry: bot traces (inbound, dispatch, conversations, sends, AI) and bot.metrics() as OTel metrics. @opentelemetry/api as an optional peer. |
@botmesh/events |
Experimental | Versioned envelopes, idempotent journal, retries and DLQ for asynchronous processes. |
@botmesh/rag |
Experimental | RAG for @botmesh/ai: loaders, chunking, pluggable embeddings (OpenAI-compatible, Ollama, local hashing) and an in-memory vector index with optional JSON persistence. |
@botmesh/voice |
Experimental | Voice: voice-note transcription (OpenAI-compatible, Deepgram) and spoken replies (OpenAI, ElevenLabs). |
@botmesh/chatwoot |
Experimental | Chatwoot bridge: two-way sync and human handoff driven by Chatwoot agents. |
@botmesh/tickets |
Experimental | Support tickets and queues (ctx.tools.tickets): queue position, business hours and store persistence. |
@botmesh/moderation |
Experimental | Group moderation: anti-spam, word/regex and invite-link filters, warn/mute/kick/delete actions. |
@botmesh/dialogflow |
Experimental | Dialogflow ES/CX: detectIntent over REST (service-account JWT, no Google SDK) and intent routing to flows. |
| Shared infrastructure (dependencies of the Alpha packages) | ||
@botmesh/http |
Alpha | Safe HTTP client: anti-SSRF, redirect validation, timeouts and download limits. |
@botmesh/graph-core |
Alpha | Shared Meta Graph helpers (webhook verification, error mapping, ingest guard) used by meta/messenger/instagram. |
@botmesh/wa-gateway-kit |
Internal | Code shared by the WhatsApp REST gateways (evolution, wppconnect): REST client over secureFetch, outbound media resolution and LID/PN identity reconciliation. Private; not installed directly. |
@botmesh/server |
Experimental | Webhook ingress for the providers: raw body, size limits, timeouts, concurrency and health endpoints for node:http, Express, Fastify and Hono (no dependencies). |
| Product / operations (private, persistent) | ||
@botmesh/inbox |
Product | Persistent omni-channel inbox: CAS assignment, handoff, notes, unread, SLA and ledger projection (attachInbox). |
@botmesh/crm |
Product | Contacts, tags, attributes, consent (lossless CAS) and per-tenant segments. |
@botmesh/hub |
Product | Per-tenant plugin registry: validated manifests and permission-gated enabling. It does not run or sandbox code. |
@botmesh/campaigns |
Product | Consent-aware campaigns: durable per-recipient reservations (TTL), atomic settlement and sendCampaign() over bot.broadcast(). |
@botmesh/deployments |
Product | Immutable versions, active version, gate reservations, rollback and audited gate runs (including the golden-transcript gate). |
@botmesh/tenant-kv |
Internal | Per-tenant JSON documents with compare-and-set over any DurableKv: the base of the product packages. |
@botmesh/flow-schema |
Internal | Versioned JSON schema for code-free flows, safe expressions, compilation to CompiledFlow, reverse export, migrations and deployment helpers. |
| Tooling | ||
create-botmesh |
Alpha | CLI scaffolder (npm create botmesh), 10 templates: baileys, meta, telegram, ai and the use-case ones games, support, store, restaurant, clinic, ai-full. Every project ships an AGENTS.md for coding agents. |
eslint-plugin-botmesh |
Experimental | ESLint rules for bots: v1 API leftovers, blocking runtime.enter, async install, empty triggers, ask without timeout and per-user global state. |
@botmesh/sandbox |
Experimental | Local simulators of WhatsApp Cloud API, Messenger, Instagram, Twilio, Gupshup, HighLevel, TikTok, Discord and Telegram (signed webhooks, realistic errors, request-shape checks) with a web chat UI: pnpm sandbox. Docker suites for Evolution API, WPPConnect, Chatwoot and Mailpit. |
@botmesh/mcp |
Experimental | Stdio MCP server (no dependencies) for agents: validates, compiles, renders, lints, migrates and diffs JSON flow documents without starting a bot; with --docs it searches these guides. |
Start with the core README for the quickstart.
Alpha — published under the
alphadist-tag. The packages below are on npm, butchangeset publishdoes not create alatesttag, so the commands use@alpha. Only the Alpha packages in the table above are published; the rest are private.
pnpm add @botmesh/core@alpha @botmesh/baileys@alpha # WhatsApp bot (Baileys)
# or @botmesh/core@alpha @botmesh/meta@alpha # official WhatsApp bot (Cloud API)
pnpm add @botmesh/ai@alpha @anthropic-ai/sdk@^0.68 # + AI (optional; install the SDK of the provider you use)The @alpha tag is mandatory while the alpha is the only published series: changeset publish in
prerelease mode creates the alpha dist-tag, not latest, so pnpm add @botmesh/core without a tag will not
resolve. Once a stable version ships the tag can be dropped (see prerelease mode).
Requires Node >= 22. Every package is ESM-only.
Install an AI SDK inside the range @botmesh/ai declares as a peer (@anthropic-ai/sdk@^1, openai@^7, @google/genai@^2; the previous majors @anthropic-ai/sdk@^0.68 and openai@^6.48 still work): unlike npm, pnpm add <sdk> installs the newest major and only warns when it falls outside the peer range.
The quickest start is the scaffolder: npm create botmesh@alpha my-bot (see create-botmesh).
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.
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 sitePer package: pnpm --filter @botmesh/ai test, pnpm --filter @botmesh/core build, and so on.
| 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.
- Guides:
docs/(English indocs/guide/, Spanish indocs/es/guide/). There is no published site; to read them as a website locally:pnpm docs:dev. - Migration guide v1 → v2:
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/anddocs/superpowers/plans/.
See CONTRIBUTING.md. Relevant changes go in CHANGELOG.md.
MIT © Andres Aya