A deep dive into engineering Bottaviano: solving FloodWait cascading storms, turning Telegram Forum Topics into a reactive GUI, and implementing client-side encrypted account backups.
Telegram has evolved far beyond a simple instant messaging app. For thousands of community leaders, creators, freelancers, and businesses, it is the primary operating system for client communication, sales, and community building.
However, power-using Telegram comes with friction:
Fragmented Attention: Important direct tags and replies get drowned in dozens of active groups and channels.
Manual Repetition: Broadcasters and managers waste hours copy-pasting recurring announcements across multiple target communities.
Disaster Risk: If an account gets restricted, banned, or access is lost, years of contacts, custom chat folders, and Saved Messages evaporate with zero official recovery mechanism.
To solve this, we built Bottaviano - an all-in-one automation platform and personal assistant that runs directly on Telegram via MTProto.
In this article, we’ll explore the technical challenges behind building Bottaviano, how we tamed Telegram's strict rate limits, and why we designed the entire user interface inside Telegram itself.
🛠️ The Architecture Stack
Under the hood, Bottaviano is designed as an asynchronous, distributed Python system:
Engine: Python 3.10+ running Telethon (async MTProto client framework).
Storage & Caching: PostgreSQL (with PgBouncer connection pooling) and Redis for high-throughput state caching and rate limiting.
Orchestration: Docker Compose multi-container architecture with isolated worker pools.
Secrets Management: Doppler for zero-exposure environment credentials.
Web Portal: Nuxt 3 & Tailwind CSS for billing, account verification, and help documentation.
💡 Engineering Challenge #1: Using Telegram Supergroups as a Reactive GUI
Traditional SaaS platforms require you to leave your chat app and open a web dashboard to configure workflows. We asked ourselves: Why can't the entire interface live inside Telegram itself?
When Telegram introduced Forum Supergroups (topics), we leveraged them as a dynamic dashboard:
- Auto-Provisioning: Upon setup, Bottaviano automatically spins up a dedicated private control supergroup configured with forum topics.
-
Topic Separation: Each core capability lives in its own dedicated topic (
#Notifications,#Account-Recovery,#Lists,#Triggers,#Support). - Interactive Menus: Instead of raw text commands, the bot renders inline keyboards and rich HTML views, turning topics into reactive control panels with zero app-switching with the new Rich Message format
⚡ Engineering Challenge #2: The Cascading "FloodWait" Storm
Anyone who has built production bots on Telegram's MTProto protocol knows the dread of FloodWaitError.
When an account performs too many actions (scanning chats, forwarding messages, or fetching entities), Telegram instructs the client to wait $N$ seconds. In naive multi-handler architectures, a single FloodWaitError can trigger a catastrophic failure: other concurrent handlers continue firing API requests, turning a 5-second backoff into a 24-hour lockout.
To solve this, we implemented a centralized FloodWaitManager:
- Global Session State: Every outgoing request passes through an execution gate that monitors the active backoff state for that user session.
-
Request Serialization: When a
FloodWaitErroris caught, all pending tasks for that session are paused, queued, and serialized until the expiration timestamp elapses. -
Aggressive Entity Caching: Static user data like
get_me()is cached with a 24-hour TTL in memory and invalidated strictly on reconnect, cutting redundant MTProto queries by over 60%.
🛡️ Engineering Challenge #3: Zero-Knowledge Account Disaster Recovery
Losing a primary Telegram account to a false-positive ban or device theft can be devastating. However, backing up private chats, contacts, and media presents an enormous security and privacy challenge.
We engineered Account Recovery with strict privacy principles:
- Client-Side Passphrase Encryption: Before any account metadata (contacts list, joined channels, custom folder structure, and Saved Messages) is archived, the payload is encrypted using the user's secret password.
- Multi-Part Storage: Large message histories and media are chunked and dispatched into encrypted backup envelopes.
- 5-Minute Full Restore: If disaster strikes, the user connects a new account, inputs their passphrase, and Bottaviano automatically reconstructs their contacts, rejoins their channels, and rebuilds their colored Telegram folder tabs in minutes.
🚀 The 5 Core Modules of Bottaviano
Here is what the engine executes 24/7 once deployed:
1. 📋 Automated Distribution Lists
Enables rule-based message broadcasting between source and recipient groups:
- Standard Mode: Periodic delivery of fixed notices.
- ADV Mode: Pulls random, dynamic messages from designated repository groups.
- Media Mode: Rotates visual assets while preserving custom formatted captions.
- Folder Sync: Directly syncs with Telegram’s native chat folders to automatically add or remove destination groups without manual ID entry.
2. ⚡ Keyword Triggers
An instant auto-responder supporting formatting, inline buttons, and rich media. Triggers can be scoped as Private (activated only by the account owner), Public (triggerable by group members), or Chat-Specific with built-in loop guards to prevent bot-to-bot recursion.
3. 🔔 Centralized Notifications Hub
Eliminates notification fatigue. Bottaviano acts as a personal sieve, intercepting:
- Direct
@usernametags - Replies to your messages
- Specific custom keywords you choose to monitor
Alerts are piped directly into the dedicated #Notifications topic with deep links (t.me/c/...) that jump straight to the source message.
4. 💤 AFK Secretary (Smart Auto-Responder)
When you step away, Bottaviano monitors private incoming chats. It replies with your custom absence status, prevents repetitive message spam to frequent senders, and automatically deactivates as soon as you send your first message upon returning.
5. 🛡️ Account Recovery
Continuous, passphrase-encrypted snapshots of contacts, private dialog mappings, joined groups/channels, Telegram folders, and media-rich Saved Messages.
🎯 What We Learned Building on MTProto
Building on top of Telegram's userbot API (Telethon) alongside the official Bot API taught us key lessons:
- Never treat chat entities as static: Usernames change, channels get migrated to supergroups, and access hashes shift. A robust caching and entity-resolution layer is vital.
- Respect the API limits proactively: Do not wait for exceptions to trigger backoff; rate-limit client actions client-side before Telegram's servers enforce it.
- UX belongs where the user already is: Embedding configuration dashboards directly into Telegram Forum topics resulted in significantly higher daily user engagement than traditional web apps.
🔗 Try Bottaviano
Bottaviano is live and operational with a Free Basic tier for personal productivity and a Pro tier for community managers and power users.
- Website: bottavia.no
-
Explore the Bot: Search for
@bottaviano_boton Telegram to get started.
Have questions about our MTProto architecture, Telethon concurrency, or Telegram bot engineering? Drop your thoughts in the comments below!
Top comments (0)