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

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.

Official Plugins

References

Core

Features

Infrastructure

Plugins

Examples