Skip to content

About

An asyncio Telegram admin/moderator bot written in Python 3.12, built on aiogram 3 and managed with uv.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

nacho-moderator

CI Python 3.12 uv License: GPL-3.0

nacho-moderator cover

An asyncio Telegram admin/moderator bot written in Python 3.12, built on aiogram 3 and managed with uv.

Features

  • Moderation commands: /ban, /unban, /kick, /mute, /unmute, /del, /pin, /unpin, /purge, with 30s/10m/2h/7d/1w durations.
  • 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 /settings panel.
  • 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.
  • getUpdates long-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.

How it works

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
Loading

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 / ...
Loading

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.

Requirements

  • Python 3.12.
  • uv (provisions Python 3.12 if needed).

Quick start

uv sync
uv run pytest

Create 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.toml

In 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.

Configuration

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.

Commands

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.

Deployment

sudo install -m 0644 packaging/nachomoderator.service /etc/systemd/system/
sudo systemctl enable --now nachomoderator.service

Docker and webhook setup are covered in docs/deployment.md.

Development

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 floors

See docs/testing.md and CONTRIBUTING.md.

API reference

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/docs

CI builds it (docs-build) and publishes it to GitHub Pages from main and tags. The generated HTML is not committed.

Project layout

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

Troubleshooting

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.

Security

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.

License

GPL-3.0-or-later. See LICENSE.

Acknowledgements

Built on aiogram and packaged with uv.

About

An asyncio Telegram admin/moderator bot written in Python 3.12, built on aiogram 3 and managed with uv.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages