gramio

GramIO GramIO is a modern, type-safe Telegram Bot API framework for TypeScript. It runs on Node.js , Bun , and Deno with full Bot API coverage, a composable plugin system, and first-class TypeScript support. When to Use This Skill Creating or modifying Telegram bots Setting up bot commands, callbacks, inline queries, or reactions Building keyboards (reply, inline, remove, force reply) Formatting messages with entities (bold, italic, code, links, mentions) Uploading/downloading files and media Managing user sessions or multi-step conversation flows (scenes) Writing custom plugins Configuring webhooks or long polling Handling payments with Telegram Stars Broadcasting messages with rate limit handling Building Telegram Mini Apps (TMA) with backend auth Containerizing bots with Docker Using standalone @gramio/types for custom Bot API wrappers Writing and publishing custom plugins Migrating bots from puregram, grammY, Telegraf, or node-telegram-bot-api to GramIO Quick Start npm create gramio bot-name cd bot-name npm run dev Basic Pattern import { Bot } from "gramio" ; const bot = new Bot ( process . env . BOT_TOKEN as string ) . command ( "start" , ( context ) => context . send ( "Hello!" ) ) . onStart ( ( { info } ) => console . log ( @ ${ info . username } started ) ) . onError ( ( { context , kind , error } ) => console . error ( [ ${ kind } ] , error ) ) ; bot . start ( ) ; Critical Concepts Method chaining — handlers, hooks, and plugins chain via .command() , .on() , .extend() , etc. Order matters. Type-safe context — context is automatically typed based on the update type. Use context.is("message") for type narrowing in generic handlers. Plugin system — new Plugin("name").derive(() => ({ ... })) adds typed properties to context. Register via bot.extend(plugin) . Hooks lifecycle — onStart → (updates with onError) → onStop. API calls: preRequest → call → onResponse/onResponseError. Error suppression — bot.api.method({ suppress: true }) returns error instead of throwing. Lazy plugins — async plugins (without await ) load at bot.start() . Use await for immediate loading. Derive vs Decorate — .derive() runs per-update (computed), .decorate() injects static values once. Context getters — always camelCase — all ctx properties are camelCase getters ( ctx.from , ctx.firstName , ctx.chatId , ctx.messageId , etc.). Never access ctx.payload — it is the raw snake_case internal Telegram object. Use the typed camelCase getters for everything. Formatting — three critical rules (read formatting before writing any message text): Never use parse_mode — format produces MessageEntity arrays, not HTML/Markdown strings. Adding parse_mode: "HTML" or "MarkdownV2" will break the message. GramIO passes entities automatically. Never use native .join() on arrays of formatted values — it calls .toString() on each Formattable , silently destroying all styling. Always use the join helper: join(items, (x) => bold(x), "\n") . **Always wrap styled content in format\ ** when composing or reusing — embedding a Formattable in a plain template literal (`` ${bold x } ``) strips all entities. Use format${boldx}`` instead. Official Plugins Plugin Package Purpose Session @gramio/session Persistent per-user data storage Scenes @gramio/scenes Multi-step conversation flows I18n @gramio/i18n Internationalization (TS-native or Fluent) Autoload @gramio/autoload File-based handler loading Prompt @gramio/prompt Interactive single-question prompts Views @gramio/views Reusable message templates (programmatic + JSON) Auto Retry @gramio/auto-retry Retry on 429 rate limits Media Cache @gramio/media-cache Cache file_ids Media Group @gramio/media-group Handle album messages Split @gramio/split Split long messages Auto Answer CB @gramio/auto-answer-callback-query Auto-answer callbacks PostHog @gramio/posthog Analytics + feature flags OpenTelemetry @gramio/opentelemetry Distributed tracing and spans Sentry @gramio/sentry Error tracking + performance monitoring Telegram Bot API Reference Pages GramIO docs include a dedicated reference page for every Telegram Bot API method and type: Methods : https://gramio.dev/telegram/methods/{methodName} — e.g. sendMessage , createChatInviteLink , answerCallbackQuery Types : https://gramio.dev/telegram/types/{typeName} — e.g. Message , ChatInviteLink , InlineKeyboard Each page contains: GramIO TypeScript examples, parameter details, error table with causes and fixes, tips & gotchas, and related links. When a user asks about a specific Telegram API method or type, you can fetch or reference the corresponding page for accurate GramIO-specific usage. Tip for LLMs: Any GramIO docs page can be fetched as clean Markdown by appending .md to the URL: https://gramio.dev/telegram/methods/sendMessage.md — clean Markdown instead of HTML. This works for all sections of the docs, not just API pages. These pages are not included in this skill by default — fetch them on demand when the user asks about a specific method/type. To quickly find which methods exist — use the pre-built index: telegram-api-index . It lists all 165+ Bot API methods with short descriptions in one file. Load it when you need to discover a method name or confirm one exists before fetching a full page. References Core Topic Description Reference Bot Configuration Constructor, API options, proxy, test DC, debugging bot-configuration Bot API Calling methods, suppress, withRetries, type helpers bot-api Context & Updates derive, decorate, middleware, start/stop, type narrowing context Triggers command, hears, callbackQuery, inlineQuery, reaction triggers Hooks onStart, onStop, onError, preRequest, onResponse hooks Updates & Lifecycle start/stop options, graceful shutdown (SIGINT/SIGTERM) updates Features Topic Description Reference Keyboards Keyboard, InlineKeyboard, layout helpers, styling keyboards Formatting entity helpers, join (never native .join() !), variable composition, no parse_mode formatting Files MediaUpload, MediaInput, download, Bun.file() files CallbackData Type-safe callback data schemas callback-data Storage In-memory, Redis, Cloudflare adapters storage Telegram Stars Payments, invoices, subscriptions, inline invoices, refunds, test mode telegram-stars Types @gramio/types, type helpers, Proxy wrapper, declaration merging types Infrastructure Topic Description Reference Webhook Framework integration, tunneling, custom handlers webhook Rate Limits withRetries, broadcasting, queues rate-limits Docker Dockerfile, multi-stage build, Docker Compose docker TMA Mini Apps, mkcert HTTPS, @gramio/init-data auth tma Testing Event-driven bot testing, user actors, API mocking testing Migrations Load when the user wants to migrate an existing bot to GramIO. From Description Reference puregram Symbol mapping, API comparisons, checklist for puregram → GramIO refactor migration-from-puregram Telegraf Symbol mapping, context typing, Scenes/WizardScene, webhook differences, checklist migration-from-telegraf node-telegram-bot-api Symbol mapping, middleware concepts, keyboard builders, session, checklist migration-from-ntba Plugins Plugin Description Reference Session Per-user data, Redis support session Scenes Multi-step flows, state, navigation scenes I18n TS-native and Fluent internationalization i18n Autoload File-based handler discovery autoload Prompt Send + wait for response prompt Views Reusable message templates, JSON adapter, i18n views OpenTelemetry Distributed tracing, spans, instrumentation opentelemetry Sentry Error tracking, performance monitoring sentry Others auto-retry, media-cache, media-group, split, posthog other Plugin Development Writing custom plugins, derive/decorate/error, lazy loading plugin-development Examples Example Description File Basic bot Commands, hooks, error handling basic.ts Keyboards Reply, inline, columns, conditional keyboards.ts CallbackData Type-safe callback schemas callback-data.ts Formatting Entity types, join helper, variable composition, parse_mode anti-pattern formatting.ts File upload Path, URL, buffer, media groups file-upload.ts Error handling Custom errors, suppress, scoped error-handling.ts Webhook Framework integration webhook.ts Session Counters, settings, Redis session.ts Scenes Registration flow with steps scenes.ts Telegram Stars Payments, invoices, refunds telegram-stars.ts TMA Elysia server, init-data auth, webhook tma.ts Docker Graceful shutdown, webhook/polling toggle docker.ts Testing User simulation, API mocking, error testing testing.ts