aiogram

aiogram is a Python framework purpose-built for the Telegram Bot API, structured around asyncio from the ground up rather than bolted on as an afterthought. It gives bot developers a router-based dispatch system, a pluggable finite state machine for conversational flows, and a middleware pipeline for cross-cutting concerns like logging, throttling, and dependency injection — the same architectural vocabulary web frameworks use, applied to bot event handling.

The library’s Bot API surface is autogenerated directly from Telegram’s official schema, so new API methods and types land quickly after Telegram ships them, fully typed and mypy-checkable. Combined with magic filters for expressive handler conditions and first-class webhook and polling support, aiogram functions less like a thin API wrapper and more like a complete application framework for anything that talks to Telegram — from simple command bots to large, stateful multi-router systems.

What You Get

• A Dispatcher and nested Router system for organizing handlers across blueprints, with support for splitting large bots into independent, composable routers
• A built-in finite state machine (FSM) with pluggable storage backends (in-memory, Redis, MongoDB) for stateful, multi-step conversation flows
• Magic filters — a fluent, chainable expression syntax for writing handler conditions against incoming update fields without boilerplate
• A middleware pipeline that wraps both incoming updates and outgoing Bot API calls, enabling logging, throttling, and dependency injection
• An autogenerated, fully typed Bot API client covering the entire Telegram Bot API surface, regenerated as Telegram updates its schema
• Both long-polling and webhook transport support, including an aiohttp-based webhook server ready for production deployment
• Built-in i18n/l10n support via GNU Gettext or Fluent for shipping bots in multiple languages

Common Use Cases

• Building customer-support or FAQ bots that walk users through multi-step flows using the FSM
• Running high-throughput notification and broadcast bots that rely on aiohttp’s async I/O to handle many concurrent chats
• Building bots that accept payments via Telegram Stars or the Bot Payments API
• Structuring large bot codebases into independently maintained feature routers that plug into one root Dispatcher
• Deploying webhook-based bots behind a production ASGI/aiohttp server instead of long polling
• Building multilingual bots using aiogram’s integrated Gettext/Fluent-based i18n system

Under The Hood

Architecture aiogram is organized around a Router/Dispatcher hierarchy defined in aiogram/dispatcher/router.py and dispatcher.py: every Router owns a set of TelegramEventObserver instances (one per Telegram update type — message, callback_query, inline_query, and so on), and routers can be nested as sub-routers under a root Dispatcher, which is itself just a Router with process-lifecycle responsibilities (polling loop, signal handling, startup/shutdown hooks). Handler dispatch flows through a chain-of-responsibility pattern: an update is offered to each observer’s registered handlers, filtered by the filters module, until one accepts it or it falls through as UNHANDLED. Cross-cutting behavior — the FSM, error handling, user-context propagation — is implemented as middleware wrapping this same event pipeline (aiogram/fsm/middleware.py, aiogram/dispatcher/middlewares/), so the FSM and error handling are not special-cased into the dispatcher itself but compose through the same mechanism third-party middleware uses. This keeps the core dispatch loop small while letting nearly all framework behavior be added or replaced at the router/middleware level.

Tech Stack The framework targets modern Python (3.10+) and is built on aiohttp for both outbound Bot API calls (aiogram/client/session/aiohttp.py) and inbound webhook serving (aiogram/webhook/), with pydantic v2 backing every request/response model for runtime validation and typed access. State storage is pluggable through aiogram/fsm/storage/, with in-memory, Redis, and MongoDB backends available as optional extras, and magic-filter (a small companion library by the same maintainers) powers the fluent filter-expression syntax. Packaging uses hatchling with dynamic versioning, and the project is managed with uv/uv.lock for reproducible dependency resolution.

Code Quality The test suite spans roughly 289 test files organized by subsystem (test_dispatcher, test_handler, test_webhook, test_flags, and more), run through pytest with pytest-aiohttp, pytest-mock, and coverage reporting via pytest-cov/Codecov. Static analysis is enforced with ruff for linting/formatting and mypy (with the pydantic mypy plugin) for type checking, both wired into CI via GitHub Actions (tests.yml). Error handling favors typed, framework-specific exceptions (aiogram/exceptions.py, e.g. TelegramAPIError, TelegramNetworkError) over silent failures, and the entire public API carries type hints, letting consumers run mypy against their own bot code with confidence.

What Makes It Unique aiogram’s most distinctive trait is that its Bot API method and type layer is autogenerated from Telegram’s official Bot API schema (via a companion tg-codegen tool), so the client stays current with new Telegram API methods with minimal manual maintenance and full type coverage on day one. Combined with magic filters — a chainable expression syntax for handler conditions that reads closer to a query DSL than nested if-statements — and a middleware system applied uniformly to both incoming updates and outgoing API calls, aiogram brings web-framework-grade architecture (routers, middleware, DI-friendly patterns) to a domain most competing libraries treat as a simple polling wrapper around the Bot API.