easytg

Build Telegram bot interfaces like pages, not message handlers.

Menus, forms and navigation on top of grammY. Define a screen once and easytg sends, replies or edits it in place.

Getting started · Documentation · Examples · Try it in your browser

Why easytg?

With the plain Bot API, one screen means a command handler that sends it, a callback handler that edits it, answering the callback query, packing state into 64-byte callback_data, and escaping every user-provided string. easytg takes care of that plumbing.

With grammY alone, one screen takes three handlers:

bot.command('start', (ctx) =>
  ctx.reply(`Hi <b>${escape(ctx.from.first_name)}</b>`, {
    parse_mode: 'HTML',
    reply_markup: new InlineKeyboard().text('Order #42', 'order:42'),
  }));

bot.callbackQuery(/^order:(.+)$/, async (ctx) => {
  const id = ctx.match[1]; // unchecked string
  await ctx.editMessageText(`Order <b>${escape(id)}</b>`, {
    parse_mode: 'HTML',
    reply_markup: new InlineKeyboard().text('Back', 'home'),
  });
  await ctx.answerCallbackQuery();
});

bot.callbackQuery('home', async (ctx) => {
  // …the start screen again, as an edit this time
});

With easytg, you describe the screens and easytg sends, edits and answers:

const home = page('home').render(({ ctx, nav }) => ({
  text: md`Hi **${ctx.from?.first_name}**`,
  keyboard: [[nav.button('Order #42', order, { id: '42' })]],
}));

const order = page<{ id: string }>('order').render(({ params, nav }) => ({
  text: md`Order **${params.id}**`,
  keyboard: [[nav.button('Back', home)]],
}));

const app = new EasyTG().register(home, order);
bot.use(app);
bot.command('start', (ctx) => app.open(ctx, home));

Features

🧭 Pages & navigation. Describe screens, not API calls. Send, reply, edit, media swaps and long-text splitting are handled for you. nav.back() remembers where the user came from, and { mode: 'send' } keeps a message (like a video) instead of replacing it.
⌨️ Both keyboards. Inline buttons on pages, plus a main menu on the reply keyboard (replyMenu) with its own close button.
🖼 Media. Photos, videos, GIFs, documents, audio, albums and copies of existing messages, with optional protectContent.
🔒 Type-safe links. nav.button('Open', order, { id }) fails to compile if a param is missing or misspelled, even when pages link to each other in cycles.
📝 Dialogues. Multi-step forms with answers typed from the steps, validation (or zod/valibot schemas), choices, several options at once, number pickers, an inline calendar, file uploads, phone number, location and Mini App input, conditional steps, Back/Cancel and timeouts.
📱 Mini Apps. Buttons that open them, initData checks, acting for the user from your server, answering into the chat and sharing.
🔎 Text input on pages. page.onText turns a page into a search box or any other typed input.
🛡️ Secure by default. Escaping md/html templates, signed or stored tamper-proof button params, params validation with .params(parse) or any Standard Schema, owner-only group menus (or allowedUsers), admin-only pages, and anti-spam with events.
🌍 Languages. Your messages with t('cart.items', { count }): placeholders, plural rules, fallbacks and escaping; setLocale for language pickers, remembered for notifications.
💾 Sessions and storage. State per user in a chat, per user across chats, and per chat; saved once per update, typed keys, TTLs and migrations. Built-in MemoryStorage, SqliteStorage and RedisStorage, or any database behind a 3-method interface.
⏰ Scheduled tasks and queues. Persistent task()s with retries and recurring runs, deleteLater / sendLater / broadcastLater, self-refreshing pages, and concurrency-limited queues for slow jobs.
💳 Payments. invoice pages for Telegram Stars, checkout checks and a success handler.
🚀 Production-ready. Per-user ordering of concurrent updates, loading indicators for slow pages, a throttle that keeps sends within Telegram's limits, and cluster mode sharing rate limits, locks, queues and throttling across processes (Redis/SQLite).
🔗 Deep links, inline mode, notifications, broadcasts. t.me/bot?start=… links, pages as inline results, sendTo and app.edit from cron jobs and webhooks, paced broadcast to thousands of users, autoRetry for rate limits.
📊 Events for analytics and monitoring: update (with timings), pageView, sent, dialogue events, spam, error, payment, queueWait, taskError, broadcastBatch, webAppData.
🤖 Multi-bot ready. One app instance can serve several bots sharing one storage; sessions, buttons and rate limits stay per bot.
🧪 Testable. easytg/testing runs your bot against a fake Telegram API, with no token and no network.
💬 Telegram simulator. easytg/simulator is an in-memory Telegram with users, groups, buttons, inline mode and payments, plus a chat window for the browser. The docs site uses it for live playgrounds.
👀 Preview without a token. bunx easytg preview bot.ts runs your bot file in a simulated Telegram in the browser, restarts it on save, and turns what you click into a bun test file.
⌘ Commands and relays. app.command binds /commands to pages and dialogues and syncs Telegram's command menu; app.relay lets two users talk through the bot, replies and edits included.
🗺 Flow map. app.flowchart() draws your bot as a Mermaid diagram of pages, dialogues, commands and the buttons between them.
👁 Only for you, in groups. mode: 'ephemeral' opens a page or a dialogue from a shared group menu for the presser only (Bot API 10.2 ephemeral messages); ephemeral commands; disabled buttons with nav.disabled.
✍️ Streaming. app.stream shows an AI answer as it is written (Telegram drafts in private chats, with a stop button), then sends it as a formatted message.
📰 Rich messages. rich instead of text: headings, tables, task lists, collapsible details, formulas, pictures and buttons in one message (Bot API 10.3), with md escaping user input for it.
☁️ Serverless and edge. Webhooks on Cloudflare Workers, Deno Deploy or Vercel, with Redis over HTTP and cron-driven tasks.
🪶 Zero dependencies. grammY is the only peer dependency. Bun first; works on Node ≥ 20, Deno and in browsers.

Install

bash

bun add easytg grammy

bash

npm install easytg grammy

Quick start

import { Bot } from 'grammy';
import { EasyTG, md, page } from 'easytg';

const home = page('home').render(({ ctx, nav }) => ({
  text: md`Hello **${ctx.from?.first_name}**!`,
  keyboard: [[nav.button('👋 About', about)], [nav.close()]],
}));

const about = page('about').render(({ nav }) => ({
  text: 'Built with **easytg**.',
  keyboard: [[nav.button('⬅️ Back', home)]],
}));

const bot = new Bot(process.env.BOT_TOKEN!);
const app = new EasyTG().register(home, about);

bot.use(app); // register before your other handlers
bot.command('start', (ctx) => app.open(ctx, home));
bot.start();

Next, Getting started walks through building a small shop bot with pages, a form and sessions in about ten minutes.

Core concepts


`page(id).render(fn)`	A screen. `render` returns `{ text, photo, keyboard }`, a redirect, or a dialogue to start. Pages can also validate params (`.params`), show a loading indicator (`.loading`) and take typed text (`.onText`).
`nav`	Builds buttons and navigation: `nav.button`, `nav.self`, `nav.back`, `nav.home`, `nav.close`, `nav.url`, `nav.webApp`, `nav.pay`, `nav.deepLink`, and the render results `nav.redirect` / `nav.startDialogue`.
`replyMenu([...])`	A main menu on the reply keyboard; its buttons open pages or start dialogues.
`dialogue(id).steps([...])`	A multi-step form. Answers arrive in `onFinish`, typed from the steps.
`session`	State of the user in this chat; `app.userSession(ctx)` follows the user into every chat, `app.chatSession(ctx)` is shared by a chat. All saved automatically.
Middlewares	Run before every page and dialogue, for login checks, admin-only screens and logging.
`app.open(ctx, page)`	Shows a page: edits the message when a button was pressed, replies otherwise.
`app.sendTo` / `app.edit` / `app.broadcast`	Send or update pages without an incoming update: notifications, status cards, newsletters.
`task(id).run(fn)`	A job that runs later (`app.schedule`), saved in storage so it survives restarts.

// A dialogue in a nutshell
const signup = dialogue('signup')
  .steps([
    {
      id: 'name', type: 'text', text: 'Your name?',
      validate: (v) => v.length >= 2 || 'Too short',
    },
    {
      id: 'plan', type: 'choice', text: 'Plan?',
      options: [{ text: 'Free', value: 'free' }, { text: 'Pro', value: 'pro' }],
    },
  ])
  // answers: { name: string; plan: 'free' | 'pro' }, read off the steps
  .onFinish(({ answers }) => ({
    text: md`Welcome, ${answers.name}! Plan: ${answers.plan}`,
  }));

Examples

Example	Shows
`getting-started.ts`	The shop bot from the getting-started guide
`shop.ts`	Reply-keyboard menu, catalog with pagination and Back, album gallery, checkout with size, phone number and location
`media.ts`	Photo, video, GIF, document (generated), audio and album pages
`search.ts`	A searchable catalog with `page.onText`, in two languages with `t()`
`course.ts`	Members-only videos copied from a storage channel with `protectContent`, access requests approved by an admin, `app.edit`, videos that delete themselves (`deleteAfterMs`)
`reminders.ts`	Reminders that survive restarts: scheduled and recurring tasks in SQLite
`queue.ts`	Slow AI-style jobs behind a queue: concurrency, one job per user, place in line
`payments.ts`	A Telegram Stars shop: invoices, stock check at checkout, delivery, refunds
`inline.ts`	Product pages shared with `@yourbot query`, params checked by a schema, cached photo file ids
`mini-app.ts`	A bot and its Mini App in one file: a shop with a checked server API, a color picker step, feedback, sharing
`sessions.ts`	State per chat, per user across chats, and per group, side by side
`loading.ts`	Slow pages with placeholders, "typing…" and toasts that only show when needed
`throttle.ts`	Keeping sends within Telegram's limits, with rules per chat
`group.ts`	A group bot: admin-only settings, a self-refreshing scoreboard, a quiz with a timeout
`production.ts`	Redis or SQLite, several processes with `cluster`, webhooks
`broadcast.ts`	Newsletter: subscriptions, admin-only compose dialogue, a background broadcast with live progress, `broadcastLater`, events
`match.ts`	A swipe-style "meet people" bot: profile cards with ❤️ 💌 👎 💤 on the reply keyboard, sign-up dialogue, likes, matches and anonymous chats (relay), `app.command`
`booking.ts`	Table reservations: an inline calendar (`date`), a guest counter (`number`) and extras (`multiChoice`)
`support.ts`	A support desk: tickets, an agent and a customer talking through the bot (`app.relay`), a link filter, ratings
`team.ts`	A group board where settings and votes open for the presser only (ephemeral pages, dialogue and commands), `nav.disabled`
`ai-chat.ts`	An AI chat whose answers stream in as a rich draft with ⏹ Stop (`app.stream`), with a fake model
`rich.ts`	A handbook of rich messages: a pricing table, collapsible FAQ with a button inside the text, release notes from blocks
`flowchart.ts`	A bot that sends its own map (`app.flowchart()`)
`cloudflare-worker.ts`	A Cloudflare Worker: webhook, Redis over HTTP, a Cron Trigger for scheduled tasks
`captcha.ts`	Button and typed captchas, server-side answers, per-key TTL
`notify.ts`	SQLite storage, tamper-proof buttons, `sendLater` notifications that survive restarts
`locales/id.ts`	Translating the built-in texts
`testing.test.ts`	Testing a bot with `easytg/testing`: navigation, dialogues, errors, broadcasts

bash

BOT_TOKEN=123:abc bun run examples/captcha.ts

Documentation

Docs site: these docs with live playgrounds, and every example running in your browser.
Getting started: a hands-on tutorial.
Documentation: one page per feature.
- UI: Pages · Media · Main menu · Commands · Flow map · Dialogues · Text input · Text formatting · Rich messages · Languages · Inline mode · Mini Apps · Groups · Streaming
- Data: Sessions · Storage · Button params · Deep links
- Beyond one update: Notifications & broadcast · Relays · Scheduled tasks · Queues · Payments
- Production: Anti-spam · Scaling · Serverless and edge · Security · Events · Error helpers · All options · Testing · Preview · Simulator
API reference: every export and app method.
Migrating: breaking changes and how to update.
Changelog

Requirements

grammY ≥ 1.30
Bun, Node.js ≥ 20, Deno, or a browser
TypeScript is optional but recommended: it type-checks navigation.

Contributing

Issues and pull requests are welcome.

bash

bun install
bun test            # unit and integration tests (fake Telegram API)
bun run typecheck
bun run build
bun run docs:dev    # the docs site with its playgrounds, at localhost:5173

Releases are automated. See RELEASING.md.

easytg ​

Why easytg? ​

Features ​

Install ​

Quick start ​

Core concepts ​

Examples ​

Documentation ​

Requirements ​

Contributing ​

License ​

easytg

Why easytg?

Features

Install

Quick start

Core concepts

Examples

Documentation

Requirements

Contributing

License