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

Quick Start

bash

npm create gramio bot-name
cd bot-name
npm run dev

Basic Pattern

typescript

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.

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
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

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	bold, italic, code, pre, link, mention, join	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

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
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	All entity types, join helper	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

gramio

NPX Install

Tags

SKILL.md Content