Yet Another tElegram Bot Api Library
type-safe · chainable · plugin-first · batteries included
repository structure
this repository is a pnpm monorepo for the yaebal telegram bot framework — the core plus a set of first-party plugins:
- packages tree — the framework and every plugin
- core tree & readme —
Bot,Composer, context, filter queries, media - yaebal — batteries-included meta package: core + contexts + common plugins, one import
- create-yaebal —
pnpm create yaebalscaffolder for a new bot - @yaebal/types — full Bot API types, code-generated from the schema
- @yaebal/contexts — per-update context classes with auto-generated shortcut methods
- @yaebal/test — the most complete test framework for Telegram bots
- examples tree — runnable bots you can clone and run
- docs app — the SvelteKit documentation site
- architecture — design, plugin catalog, roadmap
examples
runnable, single-file bots under examples/ — clone, drop a token in
.env, and run. each is a workspace package, so it tracks the local source.
| example | what it shows | run |
|---|---|---|
| basic | a tour wiring most plugins — keyboard, callback-data, session, morda, i18n, scenes, prompt, media | pnpm --filter @yaebal/example-basic dev |
| keyboard | every @yaebal/keyboard feature — button types, styling, dynamic buttons, request user/chat/managed-bot | pnpm --filter @yaebal/example-keyboard dev |
| simple | toml routes with a typescript handler registry | pnpm --filter @yaebal/example-simple dev |
| onboarding | first-run product tour with typed flow controls, inline buttons and opt-out state | pnpm --filter @yaebal/example-onboarding dev |
| rich-messages | @yaebal/rich tour — block/inline builders, sendRichMessage, streaming a draft, reading rich_message back | pnpm --filter @yaebal/example-rich-messages dev |
| panel | the operator panel end-to-end: avatars, media viewer, keyboards, callbacks, events | pnpm --filter @yaebal/example-panel dev |
need a fresh project instead of the monorepo? scaffold one with
create-yaebal:pnpm create yaebal my-bot. it opens a centred, keyboard-driven ansi wizard that runs everywhere out of the box (node 20+/bun/deno · 10 templates · every@yaebalplugin), falls back to plain prompts without a tty, and takes flags for ci —--plugins all --yes.
plugins
| package | what |
|---|---|
| @yaebal/again | auto-retry on 429 / flood-wait / transient 5xx |
| @yaebal/session | per-chat session with pluggable storage |
| @yaebal/keyboard | fluent inline & reply keyboard builders |
| @yaebal/callback-data | typed callback_data pack / unpack |
| @yaebal/filters | composable, type-narrowing update filters (ctx.filter) |
| @yaebal/fmt | html / md tagged templates with auto-escaping |
| @yaebal/rich | sendRichMessage / sendRichMessageDraft: block builder + streaming drafts |
| @yaebal/morda | dialogs engine + jsx/hooks (react-for-telegram) |
| @yaebal/i18n | per-chat locale, ctx.t / ctx.changeLanguage |
| @yaebal/scenes | step-by-step wizards over multiple messages |
| @yaebal/onboarding | declarative first-run tutorials with inline controls |
| @yaebal/conversation | await-style multi-step dialogs (coroutine, no replay) |
| @yaebal/prompt | ask a question, handle the next message |
| @yaebal/router | file-based routing from a routes/ directory |
| @yaebal/toml | declarative toml routes with a handler registry |
| @yaebal/throttle | space out outgoing api calls to avoid 429s |
| @yaebal/files | resolve and download telegram files |
| @yaebal/ratelimiter | drop updates from users who spam |
| @yaebal/broadcast | send a message to many chats |
| @yaebal/panel | framework-agnostic operator panel with media, keyboards and event timeline |
| @yaebal/web | run your bot on edge/web runtimes via webhooks |
| @yaebal/runner | concurrent long-polling for scale |
| @yaebal/media-group | collect album updates into one handler |
| @yaebal/media-cache | reuse a file_id instead of re-uploading |
| @yaebal/split | break long messages into telegram-sized chunks |
| @yaebal/commands | one registry for handlers + the / command menu |
| @yaebal/pagination | paginated lists with inline prev/next |
| @yaebal/preview | render telegram-style chats to SVG |
| @yaebal/workers | worker_threads pool to offload CPU-heavy work |