Protect Your Telegram Group from Spams with TG-Spam with Full OpenAI Integration, Totally Free

Hazem Abbas

Jun 30, 2025 — 3 min read

Table of Content

What is TG-Spam?

TG-Spam is a free effective, self-hosted anti-spam bot specifically crafted for Telegram groups. Setting it up is straightforward as a Docker container, needing just a Telegram token and a group name or ID for the user to get started.

Once activated, TG-Spam oversees messages, leveraging an advanced spam detection methods to pinpoint and eliminate spam content.

TG-Spam also can easily work with several AI models to provide several AI models!

How does it Work?

TG-Spam keeps an eye on messages in Telegram groups, looking out for spam. It's quick to act, deleting spammy messages and banning the users who send them. The bot is also smart and gets smarter over time, learning from human guidance to catch new kinds of spam.

It is a self-hosted tool that's pretty flexible in how you set it up, working great as a Docker container on anything from a small VPS to a Raspberry Pi. Plus, its Docker image supports various architectures like amd64, arm64, and armv7, and there are also binaries available for Linux, macOS, and Windows.

TG-Spam can also run as a server, providing a simple HTTP API to check messages for spam. This is useful for integration with other tools, not related to Telegram.

In addition, it provides WEB UI to perform some useful admin tasks. For more details see WEB UI section below. All the spam detection modules can be also used as a library.

Features

Message Analysis: It evaluates messages for similarities to known spam, flagging those that match typical spam characteristics.
Integration with Combot Anti-Spam System (CAS): It cross-references users with the Combot Anti-Spam System, a reputable external anti-spam database.
Spam Message Similarity Check: TG-Spam assesses the overall resemblance of each message to known spam patterns.
Stop Words Comparison: Messages are compared against a curated list of stop words commonly found in spam.
OpenAI Integration: TG-Spam may optionally use OpenAI's GPT models to analyze messages for spam patterns.
Emoji Count: Messages with an excessive number of emojis are scrutinized, as this is a common trait in spam messages.
Meta checks: TG-Spam can optionally check the message for the number of links and the presence of images, forwarded messages, etc. If the number of links is greater than the specified limit, or if the message contains images but no text, it will be marked as spam.
Custom Lua Plugins: TG-Spam supports custom spam detection logic through Lua plugins. Users can write their own Lua scripts to detect specific patterns or behaviors without modifying the main codebase.
Automated Action: If a message is flagged as spam, TG-Spam takes immediate action by deleting the message and banning the responsible user.
AI Integeration