Dispatch Modes
How the engine responds to Telegram while handlers run. Wiring (SingleBotEngine, adapters, routes) lives in First webhook and the Engines guide.
One update, end to end
Telegram sends a POST with JSON. The adapter normalizes it; the engine resolves the bot, runs security, and dispatches to aiogram.
By default the HTTP response is an empty 200 while handlers run in the background. User-facing replies go through the Bot API in a separate call — not inside the webhook body.
The diagram above is the canonical request flow. Other pages link here instead of repeating it.
What each layer is responsible for
| Layer | Responsibility | Does not |
|---|---|---|
| Web framework (FastAPI, aiohttp, …) | TLS, routing, middleware, running the server | Parse Telegram updates or call handlers |
| Web adapter | Register POST, map request/response types |
Choose bot, verify Telegram, dispatch |
Route |
Build the public setWebhook URL; match path and query on incoming requests |
Run security or handlers |
Security |
Verify secret token and optional checks before dispatch | Register routes or call setWebhook |
| Engine | Resolve bot, dispatch update, lifecycle, set_webhook() / add_bot() |
Replace aiogram routers |
aiogram Dispatcher |
Handlers, filters, FSM, middleware | Expose a public HTTPS endpoint |
Background vs foreground
handle_in_background=True is the default.
| Mode | Telegram gets | Handler returns TelegramMethod |
Use when |
|---|---|---|---|
| Background | Empty 200 immediately |
Sent separately via Bot API | Normal bots; default choice |
| Foreground | Waits for handler; may stream method in HTTP body | Streamed as webhook reply | Saving one Bot API round-trip is a deliberate optimization |
Background mode
Engine spawns dispatcher.feed_raw_update() in a tracked background task and immediately returns 200 {} to Telegram. The HTTP response is sent before the handler runs.
If a handler returns a TelegramMethod, the engine sends it via a separate Bot API call (dispatcher.silent_call_request()).
Warning
Webhook replies are not available in background mode. Any TelegramMethod returned by a handler becomes a regular Bot API call instead of an in-response reply.
Foreground mode
Engine awaits dispatcher.feed_webhook_update() before responding. If a handler returns a TelegramMethod, it is streamed back as a Telegram-compatible multipart response — saving one round-trip to the Bot API.
engine = SingleBotEngine(
dispatcher,
bot,
web=web,
route=route,
handle_in_background=False,
)
from aiogram.methods import SendMessage
from aiogram.types import Message
@router.message()
async def echo(message: Message):
return SendMessage(chat_id=message.chat.id, text=message.text)
Warning
Foreground mode keeps the Telegram HTTP connection open until the handler completes. Avoid long I/O, external API calls, or file uploads inside handlers — use background mode for those cases.
| Background | Foreground | |
|---|---|---|
| Response time | Immediate | After handler completes |
| Webhook reply | Not available | Available |
| Extra Bot API call | Yes, if handler returns a method | No |
| Safe for slow handlers | Yes | No |
Startup and shutdown
Engine lifecycle (workflow data, 503 during shutdown, task draining): SingleBotEngine · TokenEngine.