aiogram — Modern Async Telegram Bot Framework for Python

Introduction

aiogram is a modern, fully asynchronous framework for the Telegram Bot API written in Python. Built on top of asyncio and aiohttp, it provides a middleware-based architecture, a finite state machine (FSM) for managing multi-step conversations, and built-in internationalization support, making it well-suited for production Telegram bots of any complexity.

What aiogram Does

• Provides a fully async interface to all Telegram Bot API methods
• Implements a middleware pipeline for request/response processing (logging, auth, throttling)
• Includes a built-in finite state machine (FSM) for managing multi-step user conversations
• Supports both polling and webhook modes for receiving updates
• Offers routers for organizing handlers into modular, composable groups

Architecture Overview

aiogram 3.x uses a Dispatcher that routes incoming Telegram updates through a middleware chain to registered handlers. Handlers are organized in Routers, which can be nested for modular bot design. The FSM stores conversation state per user/chat in a configurable storage backend (memory, Redis, or custom). Filters determine which handler processes each update based on message content, type, or custom logic. The framework uses aiohttp for all HTTP communication with the Telegram API.

Self-Hosting & Configuration

• Requires Python 3.8 or newer
• Install with pip install aiogram
• Obtain a bot token from Telegram's @BotFather
• Use polling mode for development: dp.run_polling(bot)
• For production, configure webhook mode with an HTTPS-enabled web server

Key Features

• Native async/await throughout with no blocking calls
• Middleware system for cross-cutting concerns (rate limiting, logging, authentication)
• FSM with pluggable storage backends (memory, Redis, MongoDB) for conversation state
• Router-based handler organization for clean, modular bot architecture
• Built-in i18n support for multilingual bots via gettext or Fluent

Comparison with Similar Tools

• python-telegram-bot — Uses a synchronous-first design with threading; aiogram is fully async from the ground up
• Telegraf — Node.js Telegram framework; aiogram serves the same role for Python
• Pyrogram — MTProto-based client for user accounts and bots; aiogram uses the official Bot API only
• node-telegram-bot-api — Node.js equivalent; aiogram offers more structure with routers, FSM, and middleware

FAQ

Q: What is the difference between aiogram 2.x and 3.x? A: aiogram 3.x is a major rewrite with a new router-based architecture, improved middleware system, and better type annotations. It is not backward-compatible with 2.x.

Q: How do I manage conversation state (multi-step forms)? A: Use the built-in FSM. Define states as a StatesGroup, set state in handlers, and store data in FSMContext. Storage can be in-memory or Redis-backed.

Q: Does aiogram support inline mode and payments? A: Yes. It covers the full Telegram Bot API including inline queries, payments, games, and web apps.

Q: What license does aiogram use? A: MIT License.

Sources

• https://github.com/aiogram/aiogram
• https://docs.aiogram.dev