# Using Aiogram

> Use when writing, reviewing, or debugging aiogram 3 bots, or migrating from 2.x. Not for Telethon.

- Skill: `ballisarium/using-aiogram` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add ballisarium/using-aiogram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ballisarium/using-aiogram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ballisarium (https://skillmd.com/u/ballisarium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ballisarium/using-aiogram

---


# aiogram 3

Use the project's installed version and existing architecture. This material was checked against aiogram 3.31.0 / Bot API 10.3 on 2026-09-07; verify the API surface affected by the task. Examples do not authorize upgrades, new dependencies, deployment, or a bot-wide rewrite.

## Choose the smallest relevant reference

For a focused issue, read the matching sibling skill directly; do not load all of them:

| Topic | Reference |
|---|---|
| Handlers, update delivery | [Routing](../aiogram-routing/SKILL.md) |
| Commands and predicates | [Filters](../aiogram-filters/SKILL.md) |
| Middleware and injection | [Middleware](../aiogram-middlewares/SKILL.md) |
| Conversation state | [FSM](../aiogram-fsm/SKILL.md) |
| Experimental wizard API | [Scenes](../aiogram-scenes/SKILL.md) |
| Button payloads | [Callback data](../aiogram-callback-data/SKILL.md) |
| Menus and buttons | [Keyboards](../aiogram-keyboards/SKILL.md) |
| Text and entities | [Formatting](../aiogram-formatting/SKILL.md) |
| Uploads and downloads | [Files](../aiogram-files/SKILL.md) |
| Albums | [Media groups](../aiogram-media-groups/SKILL.md) |
| Webhook serving | [Webhooks](../aiogram-webhooks/SKILL.md) |
| API failures | [Errors](../aiogram-errors/SKILL.md) |
| Flood control | [Rate limits](../aiogram-rate-limits/SKILL.md) |
| Incremental output | [Streaming](../aiogram-streaming/SKILL.md) |
| Offline tests | [Testing](../aiogram-testing/SKILL.md) |

For bootstrap, lifecycle, polling, migration, or a concrete code example, use the matching heading in [core-guide.md](references/core-guide.md). Locate headings with `rg -n '^## '`, then read only the relevant range; do not load the whole guide routinely. Its reviewed examples remain available.

Use [Telegram quirks](references/telegram-quirks.md) for Telegram-specific surprises and [recipes](references/recipes.md) for a requested bot pattern.

## Inspect installed APIs

Run helpers from this skill's `tools/` with the project's Python interpreter. Resolve their paths from this skill directory, not the working directory:

- `check-version.py`: versions and drift; `get-method.py`: Bot API method arguments.
- `get-type.py`: fields/shortcuts; `get-filter.py`: filter signatures.
- `get-router-api.py`: observers; `get-exception.py`: exceptions.
- `search-source.py`: installed source; `validate-example.py`: validate examples only when relevant.

Inspect `--help` when needed. Helpers may exit non-zero for unknown names or drift; inspect rather than ignore the failure.

## Essential constraints

- Use 3.x Router/Dispatcher APIs and DefaultBotProperties; do not introduce 2.x executor, message_handler, or Bot parse_mode arguments.
- Keep Bot creation and polling out of module import time. Inject dependencies through existing workflow data. Close owned sessions and resources on shutdown.
- Answer callback queries; respect the 64-byte payload limit. Use typed CallbackData for structured payloads and builders for dynamic keyboards; simple constant payloads and static markup are valid.
- Escape dynamic message text and respect UTF-16 entity offsets. Preserve the project's existing formatting contract.
- Do not run a webhook and poller against the same token. Do not drop pending updates or change delivery mode as a side effect of a small fix.
- Handle API errors explicitly; do not swallow broad exceptions or replace TelegramRetryAfter.retry_after with a hardcoded delay.
- Never put real tokens, chat IDs, or personal data in examples, fixtures, or logs. Read credentials through existing configuration.
- Prefer relevant existing tests. Offline feed_update/fake-session tests prove only the simulated behavior; they do not establish live Telegram/Hikka parsing, permissions, or rendering.