Telegram Moderation Bot

Why this project

A community of 20,000 users generates a volume of messages that's impossible to moderate by hand. The bot filters spam, applies automatic sanctions, and manages roles, continuously, with no human intervention.

Moderating such an active community directly on production wasn't a viable option: the smallest regression could affect 20,000 people at once. That's why I strictly separated a test environment from production, each with its own Telegram bot and its own database.

How it's built

The bot runs on a Linux VPS I administer myself, as two separate instances managed by systemd: one for testing, one for production. Each has its own process, its own SQLite database, and its own Telegram token, fully isolating the two environments — a regression in test can never reach the 20,000 members of the real community.

Moderation actions (bans, message deletions, sanctions) go through a custom async queue I built in Python (asyncio), to serialize calls to the Telegram API, avoid rate-limiting, and keep SQLite writes consistent.

GitHub Actions deploys to the VPS over SSH. Both bots (test/prod) run as isolated systemd services, each with its own SQLite database, and go through a shared async queue before calling the Telegram API.

What it actually does

• Two fully isolated environments (test and production), each with its own systemd process, its own SQLite database, and its own Telegram bot — a bug in test can never reach the real community
• Automatic service restart on crash via systemd (Restart=on-failure), no manual intervention needed
• Custom async queue that serializes moderation actions (bans, message deletions, sanctions) to respect the Telegram API's rate limits and avoid concurrent writes to SQLite
• GitHub Actions pipeline that runs tests automatically on every push, then deploys to the VPS over SSH and restarts the relevant service on merge to the main branch
• Logs available via journalctl for each service, for quick incident diagnosis

By the numbers