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

1. Method chaining — handlers, hooks, and plugins chain via .command(), .on(), .extend(), etc. Order matters.
2. Type-safe context — context is automatically typed based on the update type. Use context.is("message") for type narrowing in generic handlers.
3. Plugin system — new Plugin("name").derive(() => ({ ... })) adds typed properties to context. Register via bot.extend(plugin).
4. Hooks lifecycle — onStart → (updates with onError) → onStop. API calls: preRequest → call → onResponse/onResponseError.
5. Error suppression — bot.api.method({ suppress: true }) returns error instead of throwing.
6. Lazy plugins — async plugins (without await) load at bot.start(). Use await for immediate loading.
7. Derive vs Decorate — .derive() runs per-update (computed), .decorate() injects static values once.
8. 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.
9. 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 Formattablein a plain template literal (``${boldx}``) strips all entities. Useformat`${bold`x`}`` 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