An asyncio Telegram admin/moderator bot written in Python 3.12, built on aiogram 3 and managed with uv.
- Moderation commands:
/ban,/unban,/kick,/mute,/unmute,/del,/pin,/unpin,/purge, with30s/10m/2h/7d/1wdurations. - Administrator management:
/promote(limited rights only) and/demote. - Warnings:
/warn,/unwarn,/warns,/resetwarns, with a per-chat limit and auto-action (ban/mute/kick). - Per-chat settings:
/setwarnlimit,/setwarnaction,/setlog,/reload, and an inline-keyboard/settingspanel. - Welcome and rules:
/setwelcome,/welcome on|off,/setrules,/rules, with a join welcome rendered from{first}/{mention}/{chat}/{count}. - A moderation log that mirrors every action to a configured channel.
- Temporary bans and mutes that survive a restart and lift automatically.
- Join captcha, antiflood, and word/regex blacklist automod.
- Fully asynchronous I/O on one event loop; pooled, rate-limited Bot API calls with retries.
getUpdateslong-polling or webhook mode behind a TLS-terminating proxy.- SQLite persistence with migrations, on
aiosqlite. - Graceful shutdown with a bounded drain of in-flight updates.
flowchart TD
TG[Telegram Bot API] <--> SESSION[aiogram session\nrate limiter + retries]
UPD[Update source\npolling / webhook] --> DP[aiogram Dispatcher]
DP --> MW[Context middleware\nsettings + perms + automod]
MW --> ROUTER[Command dispatch]
ROUTER <--> DB[(SQLite)]
ROUTER --> SESSION
One update, end to end:
sequenceDiagram
participant TG as Telegram
participant DP as Dispatcher
participant MW as Context middleware
participant R as Command handler
participant DB as SQLite (aiosqlite)
TG->>DP: Update (message)
DP->>MW: outer middleware
MW->>DB: load settings + admins
MW->>MW: automod (locks/blacklist/antiflood)
MW->>R: dispatch the command
R->>DB: record the action
R->>TG: sendMessage / banChatMember / ...
Updates arrive by long-polling or webhook, both feeding one aiogram dispatcher.
Every group message passes through a middleware that resolves the chat's settings
and administrators and runs automod (locks, blacklist, antiflood) before command
dispatch. All outbound calls go through a session middleware that enforces the
Bot API rate limits and retry policy. See docs/SPEC.md and
docs/architecture.md.
The bot was originally written in C11; that implementation is preserved at the
c-implementation-final git tag and superseded by this Python port. See
docs/adr/0001-python-asyncio-aiogram.md.
- Python 3.12.
- uv (provisions Python 3.12 if needed).
uv sync
uv run pytestCreate a bot with @BotFather and note its token, then:
cp config/config.example.toml config.toml
chmod 600 config.toml # the file holds the bot token; the bot refuses a group/other-readable secret
# edit config.toml and set bot_token
uv run nacho-moderator --config config.tomlIn containers or CI, where a baked-in config file is often world-readable, pass
--allow-insecure-config (or set ALLOW_INSECURE_CONFIG=1) to skip the
permission check. See docs/configuration.md.
Validate a config without starting the bot with
nacho-moderator --check-config config.toml; --log-level overrides the
configured verbosity and --version prints the version. Run
nacho-moderator --help for the full CLI reference.
Add the bot to a group, grant it the administrator rights you want it to use, and
verify with /help.
The most important keys (full reference in
docs/configuration.md):
| Key | Default | Description |
|---|---|---|
bot_token |
(required) | BotFather token; never logged. |
mode |
polling |
polling or webhook. |
db.path |
./bot.db |
SQLite database file. |
api.base |
https://api.telegram.org |
Bot API base URL. |
log.level |
info |
error, warn, info, or debug. |
See docs/commands.md for the full reference.
| Command | Role | Description |
|---|---|---|
/help /start |
anyone | Show available commands. |
/ban /unban /kick /mute /unmute |
admin | Moderation. |
/promote /demote |
admin | Grant/remove limited admin rights. |
/del /pin /unpin /purge |
admin | Message management. |
/warn /unwarn /warns /resetwarns |
admin / anyone | Warnings. |
/setwarnlimit /setwarnaction |
admin | Warning policy. |
/settings /setwelcome /welcome /setrules /rules /reload |
admin | Settings. |
/setlog |
owner | Moderation log channel. |
/lock /unlock /blacklist /antiflood /captcha |
admin | Automod. |
sudo install -m 0644 packaging/nachomoderator.service /etc/systemd/system/
sudo systemctl enable --now nachomoderator.serviceDocker and webhook setup are covered in docs/deployment.md.
uv sync
uv run ruff check . # lint
uv run mypy # type-check (strict, src + tests + scripts)
uv run pytest --cov # tests + coverage (global floor 90%)
uv run python scripts/check_coverage.py coverage.json # per-module floorsSee docs/testing.md and CONTRIBUTING.md.
The package is fully type-annotated and ships a py.typed marker; every public
module, class, and function has a Google-style docstring. Generate the HTML API
reference with pdoc:
uv run pdoc nacho_moderator -o build/docsCI builds it (docs-build) and publishes it to GitHub Pages from main and
tags. The generated HTML is not committed.
src/nacho_moderator/ the bot package
commands/ the command registry and handlers
services/ perms, settings, automod, captcha, expiry, welcome
transport/ rate limiting and retries
db/ SQLite schema, migrations, repositories
tests/ unit tests, a fake bot, and a mock API server
docs/ prose documentation
packaging/ systemd unit and Dockerfile
See docs/troubleshooting.md. Top issues: the bot
lacks a required admin right, webhook secret mismatch, chat_member updates not
delivered because the bot is not an administrator, and HTTP 429 floods.
The token is read from config or environment and redacted from logs. Webhook
updates are authenticated with a constant-time secret check. See
SECURITY.md.
GPL-3.0-or-later. See LICENSE.
