anvarnarz/killspam-bot

Killspam Bot is a self serve moderation bot for Telegram groups, built with study and IT communities in mind. Anyone can add it to their group, run one enable command, and it starts protecting the group right away. It serves many separate groups at once, and each group brings its own Google Gemini API key for the AI checks, so there is no shared cost and no shared key to leak. Even without a key, a free rule based layer keeps working on its own. The bot checks new members when they join and when they send their first message. It looks at profile pictures and descriptions for explicit content using a model called NudeNet that runs locally on the server rather than sending images to any outside service. It also blocks download links to files like APK or EXE installers and links to explicit channels, treating those as serious violations handled before any other check. An optional AI layer using Gemini can flag suspicious messages as explicit or flirtatious spam, while trying not to touch normal conversation, ads, or off topic chatter. A separate detector watches for coordinated attacks, where the same message arrives from several accounts within a couple of minutes, and removes them all at once. Responses are tiered by severity. Clear serious violations lead to an immediate ban and message deletion. Less certain cases lead to a 24 hour mute plus a review prompt sent to the group's admins, who can ban the account or restore its voice with a button in that alert. Admins also have commands to ban or mute manually, teach the bot new keywords, and flag misclassifications. The bot reports its own token usage and group statistics through commands, and sends a daily summary to its operator. Each group's Gemini key is encrypted at rest, and stored spam reports and usage logs are cleared out after 90 days. To run it yourself, you create a Telegram bot through BotFather, disable its privacy mode so it can read group messages, clone the repository, install its Python dependencies, and fill in required environment variables including a bot token, a PostgreSQL database URL, an encryption secret, and a public HTTPS address. It is built to deploy on Railway but works on any host that supports a Python worker plus PostgreSQL. The project is licensed under PolyForm Noncommercial 1.0.0, which restricts it to non-commercial use.