aiogram

3.27.0 · active · verified Fri Apr 10

aiogram is a modern and fully asynchronous framework for the Telegram Bot API, built on `asyncio`. It provides a high-level, opinionated API for creating Telegram bots efficiently. The library closely follows Telegram Bot API updates, releasing new versions frequently to incorporate the latest features and changes. The current stable version is 3.27.0.

Warnings

breaking aiogram v3 introduced significant breaking changes from v2. Key areas affected include handler registration, FSMContext usage, filters, and the main polling/webhook setup.
Fix: Consult the official migration guide for aiogram v2 to v3. Update handler decorators (e.g., `@dp.message()` instead of `@dp.message_handler`), replace `executor.start_polling` with `dp.start_polling(bot)`, and adapt filter usage to the new `F` object.
gotcha aiogram is fully asynchronous. All I/O operations and handlers must be `async def` functions and use `await`. Mixing synchronous and asynchronous code incorrectly will lead to blocking, deadlocks, or unexpected behavior.
Fix: Ensure all handlers and functions interacting with the Bot API are `async def`. Use `asyncio.to_thread` for calling blocking synchronous code if absolutely necessary within an async context.
gotcha Hardcoding your bot token directly in code is a security risk. It should be kept confidential and not exposed in version control.
Fix: Always retrieve your bot token from environment variables (e.g., `os.environ.get('TELEGRAM_BOT_TOKEN')`) or a secure configuration management system. Never commit it directly to your codebase.
gotcha aiogram frequently updates to support new Telegram Bot API features. While this is beneficial, it means that minor API changes can sometimes introduce subtle breaking changes in types or available fields.
Fix: Stay up-to-date with aiogram releases and review the changelog before upgrading to major or minor versions to understand any potential impacts on your bot's logic.
breaking aiogram v3.x has specific Python version requirements. As of v3.27.0, it requires Python `>=3.10` and `<3.15`. Python 3.9 is no longer supported as of v3.23.0.
Fix: Ensure your project runs on a supported Python version (e.g., 3.10, 3.11, 3.12, 3.13, 3.14). Upgrade your Python environment if necessary. Check PyPI `requires_python` for the exact current range.

Install

pip install aiogram Install aiogram

Imports

Bot
```
from aiogram import Bot
```
Dispatcher
```
from aiogram import Dispatcher
```
F
```
from aiogram import F
```
F is a magic filter for elegant condition checking, replacing many old filter patterns.
Message
```
from aiogram.types import Message
```

CommandStart

from aiogram.filters import CommandStart

Quickstart

This quickstart demonstrates a basic 'echo' bot using `aiogram v3`. It initializes a `Bot` and `Dispatcher`, defines handlers for the `/start` command and any text message, and then starts polling for updates. Remember to replace 'YOUR_BOT_TOKEN_HERE' or set the `TELEGRAM_BOT_TOKEN` environment variable.

import asyncio
import os
from aiogram import Bot, Dispatcher, F
from aiogram.types import Message
from aiogram.filters import CommandStart

BOT_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN', 'YOUR_BOT_TOKEN_HERE') # Replace or set env var

async def main():
    bot = Bot(token=BOT_TOKEN)
    dp = Dispatcher()

    @dp.message(CommandStart())
    async def handle_start(message: Message):
        await message.answer(f"Hello, {message.from_user.full_name}!")

    @dp.message(F.text == "hi")
    async def handle_hi(message: Message):
        await message.answer("Hi there!")

    @dp.message(F.text)
    async def handle_text(message: Message):
        await message.answer(f"You said: {message.text}")

    await dp.start_polling(bot)

if __name__ == "__main__":
    if BOT_TOKEN == 'YOUR_BOT_TOKEN_HERE':
        print("Please replace 'YOUR_BOT_TOKEN_HERE' with your actual bot token or set the TELEGRAM_BOT_TOKEN environment variable.")
    else:
        asyncio.run(main())

view raw JSON →