Engines

Written by
Updated at June 8, 2026

The engine is the runtime coordinator: it receives a normalized request from an adapter, resolves the bot, runs security, feeds the update to aiogram, and manages lifecycle.

Note

New to the library? First webhook wires SingleBotEngine first. Request flow diagram: Dispatch modes.

Which engine?

Engine How the bot is chosen Guide
SingleBotEngine Always the Bot from the constructor SingleBotEngine
TokenEngine bot_token from route parameters TokenEngine
Custom subclass Your _resolve_target / _resolve_bot logic Custom engine

Shipped engines are convenience defaults, not the only design. Database lookup or path-based bot IDs need a custom engine.

Wiring pattern

Every engine takes the same constructor arguments:

engine = SingleBotEngine(
            dispatcher,
            bot,
            web=adapter,
            route=route,
            security=security,  # optional, recommended in production
            webhook_config=webhook_config,  # optional Telegram setWebhook fields
            handle_in_background=True,  # default; see Behavior
        )

engine.register(app) exposes the local route; set_webhook() / add_bot() register with Telegram. See First webhook.

Topic Page
Background vs foreground dispatch Dispatch Modes
Telegram setWebhook fields WebhookConfig
Per-bot overrides on TokenEngine TokenEngine
HTTP errors during dispatch Errors

Tip

Keep one Dispatcher per engine unless you have a clear reason to split routing. Startup workflow data includes app, webhook_engine, and bot or bots for use in aiogram hooks.

Previous
Custom adapter
Next
SingleBotEngine