Single-bot App

Use this recipe when one deployed service handles one Telegram bot. The component choice is simple: one engine, one route, one adapter, and one bot.

Component Choices

Need	Component
One configured bot	`SingleBotEngine`
FastAPI endpoint	`FastAPIAdapter`
Public webhook URL	`Route(base_url=..., path=...)`
Telegram request verification	`Security` with `StaticSecretToken`
Telegram delivery options	`WebhookConfig`

Application Layout

app/
          bot.py
          web.py
          settings.py

The important part is that the Bot, Dispatcher, Route, Security, and adapter are wired once.

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.

FastAPI Example

from contextlib import asynccontextmanager
        
        from aiogram import Bot, Dispatcher
        from fastapi import FastAPI
        
        from aiogram_webhook import FastAPIAdapter, SingleBotEngine, WebhookConfig
        from aiogram_webhook.route import Route
        from aiogram_webhook.security import IPCheck, Security, StaticSecretToken
        
        dispatcher = Dispatcher()
        bot = Bot("BOT_TOKEN")
        
        engine = SingleBotEngine(
            dispatcher,
            bot,
            web=FastAPIAdapter(),
            route=Route(base_url="https://example.com", path="/telegram/webhook"),
            security=Security(IPCheck(), secret_token=StaticSecretToken("webhook-secret")),
            webhook_config=WebhookConfig(drop_pending_updates=True),
        )
        
        
        @asynccontextmanager
        async def lifespan(app: FastAPI):
            await engine.set_webhook()
            yield
        
        
        app = FastAPI(lifespan=lifespan)
        engine.register(app)

Add Webhook Options

from aiogram_webhook import WebhookConfig
        
        webhook_config = WebhookConfig(
            allowed_updates=["message", "callback_query"],
            drop_pending_updates=True,
            max_connections=40,
        )

Option	Why it matters
`allowed_updates`	Limits the update types Telegram sends.
`drop_pending_updates`	Drops old queued updates during deployment or first setup.
`max_connections`	Controls Telegram delivery concurrency.