telegram

name	telegram
description	Telegram Bot development playbook: bot fundamentals, aiogram 3 patterns (handlers/middlewares/FSM), webhooks, keyboard UX, inline mode, Mini Apps, payments (Stars/subscriptions), authentication. Use when building or modifying Telegram bots, setting up webhook infrastructure, implementing inline keyboards/callback queries, integrating Telegram payments or Stars, or working with aiogram 3 handlers and FSM. Keywords: Telegram, aiogram, Bot API, webhook, handlers, middlewares, FSM, inline keyboard, reply keyboard, callback_query, inline mode, Mini Apps, Web Apps, payments, Telegram Stars, Login Widget.
metadata	{"version":"3.30.0","release_date":"2026-07-17"}

Telegram (Skill Router)

Router skill: pick the reference that matches your task.

Quick Navigation

Task	Reference
New to Telegram bots	bots-overview.md
Bot capabilities overview	bot-features.md
API methods/types	bot-api.md
Webhook setup & security	webhooks.md
aiogram 3 handlers/FSM	aiogram-patterns.md
Keyboard UX	keyboard-design.md
Inline mode	inline-mode.md
Mini Apps (Web Apps)	mini-apps.md
Payments (Stars)	payments.md
Authentication (Login Widget, URL Auth)	authentication.md
Rate limits & performance	performance.md

Critical Prohibitions

• ❌ No polling + webhooks simultaneously for same bot
• ❌ No hardcoded tokens/secrets — use environment variables
• ❌ No secrets in callback_data or logs
• ❌ No ignoring answer_callback_query — always respond
• ❌ No blocking work in webhook handlers — use background tasks
• ❌ No trusting Login Widget data without hash verification

Definition of Done

• Webhook handlers validate X-Telegram-Bot-Api-Secret-Token
• Keyboards: max 2 buttons per row, mobile-first
• Callback data validated, not trusted blindly
• Handlers are idempotent or have de-duplication

Release Note (3.29.x - 3.30.x / Bot API 10.1 - 10.2)

• aiogram 3.30.0 adds full Bot API 10.2 support, and 3.29.0 added Bot API 10.1. Assume the newer method/type schema when targeting recent aiogram.
• 3.29.1 fixes a severe (exponential) slowdown when validating nested unions, so heavy handler/filter models parse far faster on the patched line.

Release Note (3.28.x / Bot API 10.0)

• aiogram 3.28.x adds Bot API 10.0 support, bringing guest-mode updates, richer poll/media flows, live photos, reaction-management methods, and managed/business-bot access settings.
• The 3.28.1+ patch line also fixes InputPollOption.media validation, so poll/media integrations should assume the newer schema and the patched aiogram serializer behavior.

Links

• Telegram Bot API
• aiogram Releases
• aiogram Documentation

Related Skills

• PostgreSQL — for database layer
• FastAPI — for API layer (if exists)