Engines

Written by
Updated at August 22, 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 dispatcher, web, route, an optional security, and handle_in_background:

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

webhook_config is not a constructor argument on SingleBotEngine — pass it to set_webhook() instead (see SingleBotEngine). TokenEngine does accept webhook_config in its constructor as a default applied to bots added without an explicit override (see TokenEngine).

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