🇺🇸English

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 ) load at . Use for immediate loading.

Official Plugins

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

Features

Infrastructure

Migrations

Load when the user wants to migrate an existing bot to GramIO.

Plugins

Examples

Weekly Installs

99

Repository

gramiojs/documentation

GitHub Stars

7

First Seen

Feb 14, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn

Installed on

codex93

opencode93

gemini-cli92

amp92

github-copilot92

kimi-cli92