Custom integrations
Written by
Updated at June 8, 2026
Built-in adapters and engines cover common setups. When one piece does not fit — another framework, database bot lookup, per-bot secrets — replace only that piece and keep the rest.
Warning
Start with First webhook and shipped components first. Custom code is easier to reason about when the default path already works.
Extension map
| You need to… | Implement | Shipped reference |
|---|---|---|
| Support another web framework | WebAdapter + WebRequest |
FastAPI, aiohttp — read source, do not copy blindly |
| Resolve bots by id, database, or custom route | BaseWebhookEngine / BaseMultiBotEngine |
SingleBotEngine, TokenEngine |
| Different secret per bot | SecretToken |
StaticSecretToken |
| Extra request rules (headers, tenancy) | SecurityCheck |
IPCheck |
| Guide | Open when |
|---|---|
| Custom adapter | HTTP stack is not FastAPI or aiohttp. |
| Custom engine | Bot selection is not fixed Bot or URL token. |
| Custom secret token | Secrets come from storage at runtime. |
| Custom checks | Verification goes beyond Telegram defaults. |
Boundaries (do not blur)
| Layer | Owns |
|---|---|
| Adapter | Framework types, POST registration, response mapping |
Route |
Public URL build + path/query match |
Security |
Verification before dispatch |
| Engine | Bot resolution, update feeding, lifecycle, setWebhook kwargs |
| aiogram | Handlers, filters, FSM |
An adapter that resolves bots, or an engine that parses framework-specific headers, couples layers and makes upgrades harder.
Layer table with examples: Dispatch modes.
Out of scope
Handler design, FSM, and Bot API usage: aiogram documentation.
Previous
Next