| name | telegram-bot |
| description | Build, architect, deploy Telegram bots on grammY 1.x + Node 24 + TypeScript 5.9. Use when: telegram bot, tg bot, grammY, Bot API, BotFather, webhook, long polling, Mini App, Telegram WebApp, initData, HMAC validation, secret_token, Telegram Stars, XTR, Payments 2.0, refundStarPayment, business connection, callback query, inline keyboard, conversation, session, sequentialize, runner, paid media, reactions, chat boost. SKIP: Python aiogram (→aiogram-python), Discord (→discord-bot-developer), Matrix/Slack/WhatsApp, Telegram desktop client. |
| stacks | ["telegram","bot"] |
| packages | ["grammy","@grammyjs/runner","@grammyjs/conversations","@grammyjs/storage-redis","@grammyjs/menu","@grammyjs/auto-retry","@grammyjs/ratelimiter"] |
| tags | ["telegram","bot","mini-app","payments","grammy"] |
| source | regenerated-zero-baseline |
| risk | high-stakes |
🎯 Version Requirements (May 2026)
Primary pins:
- Node.js:
24.x (Active LTS)
- TypeScript:
6.0.x
Source of truth: STACK_VERSIONS.md — verified 2026-05-16
Usage
Loaded automatically when its description matches the active task. Read only the section you need.
Use this skill when
- Creating a new Telegram bot or extending an existing one (grammY 1.x — the production-supported choice)
- Setting up webhooks (Fastify/Hono/Express/Cloudflare Workers) or concurrent long polling (
@grammyjs/runner)
- Implementing Mini Apps:
initData HMAC-SHA256 validation, sendData / answerWebAppQuery, deep links
- Integrating Telegram Stars (XTR) or Payments 2.0 (fiat), refunds, subscriptions, paid media
- Handling Bot API 10.0 features: business connections, reactions, chat boosts, guest mode, managed bots
- Designing sessions (RAM/file/Redis), conversations (
@grammyjs/conversations), sequentialize for scale
- Multi-instance scaling: Redis sessions, sticky routing, distributed locks, broadcast rate limits
- Adding observability (Pino, Sentry,
bot.catch), graceful shutdown, PM2/Docker/serverless deploys
- Diagnosing webhook delivery, secret_token mismatch, 409 Conflict, idempotency misses, blocked users
Do not use this skill when
- Task is Python aiogram bot — hand off to
aiogram-python (cascade marker)
- Task is Discord — hand off to
discord-bot-developer (cascade marker)
- Task is Matrix, Slack, WhatsApp, or other chat platform integration
- Task is Telegram desktop client or Telegram infrastructure development
- Task is generic Node.js webhook with no Telegram surface — use
nodejs
- Task is Mini App frontend UI design only — use
ui-ux-pro-max
Purpose
Telegram is the dominant chat platform for bot-powered products in CIS markets and increasingly worldwide. Bots handle e-commerce, subscriptions, content delivery, support, AI assistants, and payments without a separate app install. Bot API 10.0 (May 2026) adds guest mode, managed bots, reaction management, and richer business features.
This skill covers the full production lifecycle of a Telegram bot on grammY 1.x + TypeScript 5.9 + Node.js 24 — the single production framework choice as of 2026 (full Bot API 10.0 coverage, first-class TS via context flavors, active plugin ecosystem). Topics: middleware architecture, session persistence, conversation flows, inline keyboards, webhook security, payment integration (Stars XTR + Payments 2.0), Mini App connectivity, and multi-instance scaling with Redis.
