Single-bot App
Project shape for one Telegram bot on one service. For the runnable example, start with First webhook; this recipe adds structure and production knobs.
Components
| Need | Component | Guide |
|---|---|---|
| One bot | SingleBotEngine |
SingleBotEngine |
| HTTP framework | FastAPIAdapter or AiohttpAdapter |
Web adapters |
| Public URL | Route(base_url=..., path=...) |
Route |
| Request verification | Security |
Security |
| Telegram delivery | WebhookConfig |
WebhookConfig |
Suggested layout
app/
bot.py # handlers, Dispatcher, Router
web.py # FastAPI/aiohttp app, engine wiring
settings.py # tokens, base_url, secrets from env
Wire Bot, Dispatcher, Route, Security, and the adapter once in web.py. Keep handlers free of HTTP details.
Configure request verification
The engines work without security=..., but the library emits a warning because webhook endpoints are public HTTP routes.
Use a Telegram secret token, an IP check, or both for production deployments.
Webhook options
Add when defaults are not enough:
from aiogram_webhook import WebhookConfig
webhook_config = WebhookConfig(
allowed_updates=["message", "callback_query"],
drop_pending_updates=True,
max_connections=40,
)
| Option | Why |
|---|---|
allowed_updates |
Limits update types Telegram sends. |
drop_pending_updates |
Clears stale queue on deploy or first setup. |
max_connections |
Caps Telegram delivery concurrency. |
Shutdown
During shutdown the engine returns 503 for new webhook requests, waits for background tasks, then closes the bot session.
Tip
Keep expensive work off the webhook path. Acknowledge Telegram quickly; use a queue or worker for long jobs. See Dispatch Modes.