ballisarium 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 |
| Commands and predicates | Filters |
| Middleware and injection | Middleware |
| Conversation state | FSM |
| Experimental wizard API | Scenes |
| Button payloads | Callback data |
| Menus and buttons | Keyboards |
| Text and entities | Formatting |
| Uploads and downloads | Files |
| Albums | Media groups |
| Webhook serving | Webhooks |
| API failures | Errors |
| Flood control | Rate limits |
| Incremental output | Streaming |
| Offline tests | Testing |
For bootstrap, lifecycle, polling, migration, or a concrete code example, use the matching heading in 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 for Telegram-specific surprises and recipes 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.