About tg-spam — Self-Hosted Anti-Spam Bot for Telegram Groups
tg-spam is a self-hosted bot that watches one Telegram group, deletes the messages it judges to be spam and bans the people who sent them. It is written in Go by Umputun and released under the MIT licence. You run it yourself, as a Docker container or a single binary, on anything from a small VPS to a Raspberry Pi.
This page links to the official 1.27.0 binaries on GitHub. Bineret did not write tg-spam and is not affiliated with its authors.
How it decides
Each message goes through several independent checks, and any of them can flag it:
- similarity to a set of known spam samples, balanced by samples of normal messages;
- a lookup of the sender in CAS, the Combot Anti-Spam database;
- a list of stop words and phrases;
- the number of emoji;
- optional meta checks, such as too many links or an image with no text;
- optional classification by OpenAI or Google Gemini, or both at once;
- your own rules, written as Lua plugins without touching the Go code.
When a message is flagged, the bot deletes it and bans the sender. Release 1.27.0 also checks rich messages (Telegram articles) and external replies, and lets a plugin approve a message as legitimate.
It learns from your admins
The bundled samples are the author’s own collection, and the project says plainly that they will not catch everything in every group and language. The bot is built to learn instead.
Set an admin chat and every ban is reported there, with buttons to unban, confirm the ban, or see which checks fired. When an admin spots spam that got through, they forward it to the bot. The bot adds it to its samples, bans the sender and deletes the original if it can still find it. An admin replying /spam to the message does the same.
If automatic bans on a busy group feel risky, start with --training. The bot stops banning and deleting on its own, keeps reporting, and admins confirm bans by button while it learns what spam looks like in your group.
Two values to get started
A bot token from BotFather, and the group’s name or ID. Add the bot to the group as an admin, or it cannot delete anything. For a private group, turn privacy mode off in BotFather before adding the bot; if you do it afterwards, remove the bot and add it again.
Web UI and HTTP API
With --server.enabled, tg-spam serves an HTTP API and a web UI on port 8080. The UI checks a message by hand and manages spam and ham samples, stop phrases, approved users and bot settings. It sits behind basic auth, with a random password printed at startup unless you set your own. The project warns against exposing it to the internet without TLS in front, and so do we.
The detection code is also a Go library, github.com/umputun/tg-spam/lib, if you want the checks without the bot.
Limits worth knowing
One instance protects one group. For several groups you run several instances, each with its own bot token; they can share the same sample files.
The LLM checks send message text to OpenAI or Google and cost whatever those APIs charge. They are off until you configure them.
Which file to download
This page links five archives: Windows x86_64, Linux x86_64 and arm64, and macOS for Apple Silicon and Intel. The release page also has a 32-bit ARM build and .deb, .rpm and .apk packages for Linux. The project’s main route is the Docker image, ghcr.io/umputun/tg-spam, and the getting-started steps cover both.
Key capabilities
Several checks, one verdict
Spam-sample similarity, a CAS lookup, stop words, emoji count and optional meta checks run on every message, with OpenAI or Gemini as an optional extra opinion. Any of them can flag a message for deletion and a ban.
Learns from your admins
Bans are reported to an admin chat with unban and confirm buttons. Forward missed spam to the bot, or reply /spam, and it joins the samples: the sender is banned and the original deleted when it can still be found.
Training mode first
With --training the bot reports but does not ban or delete, so it can learn a live group's spam while admins confirm each ban by hand. Turn it off once the calls look right.
A web UI when you want one
--server.enabled serves an HTTP API and a web UI on port 8080 for checking messages and managing samples, stop phrases, approved users and settings, behind basic auth. Put TLS in front before exposing it.
Your own rules in Lua
Custom detection logic goes in Lua plugins, no Go changes needed. In 1.27.0 a plugin can also approve a message as legitimate, and reloading a plugin now reaches the checks that are already running.
One group per instance
Each running bot protects a single group. Several groups mean several instances with separate bot tokens, which can share their sample files.
Questions & Answers
Can one bot protect several groups?
No. One instance watches one group. Run an instance per group, each with its own bot token, since Telegram does not allow one token to be used by several running bots. The instances can share sample files.
Why is it not deleting anything?
Almost always permissions. The bot must be an admin that can delete messages and ban users, and in private groups its privacy mode must have been disabled before it was added.
Will it ban real members by mistake?
It can, especially early on. Start with --training, and use the unban button in the admin chat when it gets one wrong; the project describes unbanning as the way to teach it about false positives.
Do I need an OpenAI or Gemini key?
No. The LLM checks are optional and off until configured. Without them the bot still uses samples, CAS, stop words, emoji counts and meta checks.
Does message text leave my server?
Only for the checks that call outside services: the CAS lookup asks the CAS database about the sender, and the OpenAI and Gemini checks, if you turn them on, send the message text to those providers.
Can I use it outside Telegram?
Yes, two ways. The HTTP API has a POST /check endpoint that takes a message and user ID and returns a verdict, and the detector is a Go library at github.com/umputun/tg-spam/lib.
Where do I start if my group has no spam samples?
The bot can start from an empty set. Point --files.dynamic at a data directory, set an admin chat and --super admins, and forward spam to the bot as it appears.
Is Bineret connected to tg-spam?
No. This page describes the project and links to the release files its authors publish on GitHub.
Tutorials
1. Create the bot
In Telegram, message @BotFather, send /newbot, and pick a name ending in bot. BotFather replies with a token like 12345678:xy778Iltzsdr45tg. Keep it private.
2. Turn privacy mode off
Send BotFather /setprivacy, choose your bot and pick Disable, so the bot can read every message in the group. Do this before adding the bot. If it is already in the group, remove it and add it again.
3. Add the bot as an admin
Add it to your group and make it an admin with permission to delete messages and ban users. Without that it can detect spam but cannot act on it.
4. Run it with Docker
docker run -d --name tg-spam --restart=always \
-e TELEGRAM_TOKEN=12345678:your-token \
-e TELEGRAM_GROUP=your_group \
-e ADMIN_GROUP=-1001234567890 \
-e FILES_DYNAMIC=/srv/var \
-v "$(pwd)/var:/srv/var" \
ghcr.io/umputun/tg-spam:latest --super=your_usernameTELEGRAM_GROUP is the public group name, or the numeric ID for a private group. ADMIN_GROUP is where ban reports go. --super names the admins the bot takes /spam and /ban from.
Or run the binary
Unpack the archive for your system and run the program with the same settings as flags:
./tg-spam --telegram.token=12345678:your-token --telegram.group=your_group \
--admin.group=-1001234567890 --super=your_username --files.dynamic=./varOn Windows the program is tg-spam.exe and takes the same flags.
5. Start in training mode
Add --training for the first days. The bot reports what it would ban without banning or deleting, and admins confirm bans by button. Remove the flag once its calls look right.
6. Optional: the web UI
Add --server.enabled and open port 8080. The login is tg-spam with a random password printed at startup, or your own set with --server.auth. Put a reverse proxy with TLS in front before exposing it anywhere public.
Support
Where support comes from
tg-spam is maintained by Umputun and contributors. The full option list and guides are in the README and on tg-spam.umputun.dev. Report bugs and ask questions as GitHub issues, with your version, how you run it, and the relevant log lines with your token removed.
What Bineret covers
This page. If a download link is broken or something written here is wrong, tell us and we will fix it. We do not set up, host or moderate groups with tg-spam.
No warranty
The MIT licence provides the software as-is. An anti-spam bot acts on real people in your group, so watch it closely in training mode before letting it ban on its own.
