TG-Spam is a self-hosted, Docker-deployable anti-spam bot for Telegram groups, designed to automatically detect and remove spam messages and ban offending users. It offers a flexible, multi-layered detection approach, including message analysis, external database integration, similarity checks, stop words, optional OpenAI analysis, and custom Lua plugins, making it adaptable to various spam patterns.

How It Works

TG-Spam employs a sophisticated, configurable spam detection engine. It analyzes messages for similarity to known spam, checks against the Combot Anti-Spam System (CAS), compares against stop words, and can optionally leverage OpenAI's GPT models for contextual analysis. Additional checks include emoji count, link density, and message structure (e.g., image-only messages). Custom Lua scripts allow for user-defined detection logic, enhancing its adaptability. Detected spam results in message deletion and user banning, with configurable reporting and dry-run modes.

Quick Start & Requirements

• Install: Docker is the primary installation method (umputun/tg-spam on Docker Hub). Binaries and Homebrew installation (brew install umputun/apps/tg-spam) are also available.
• Requirements: A Telegram bot token and a group name/ID are mandatory. Admin privileges for the bot in the target Telegram group are required for moderation actions. Optional OpenAI API key for enhanced detection.
• Setup: Minimal setup involves providing the Telegram token and group ID via environment variables or command-line arguments.
• Docs: Official Documentation

Highlighted Details

• Supports custom Lua plugins for extensible spam detection logic.
• Optional integration with OpenAI's GPT models for advanced message analysis.
• Provides a web API and UI for message checking, sample management, and user administration.
• Database-driven architecture (SQLite/PostgreSQL) for storing spam/ham samples and configuration.

Maintenance & Community

The project is actively maintained by umputun. Community support channels are not explicitly mentioned in the README.

Licensing & Compatibility

The project is licensed under the MIT License, permitting commercial use and integration with closed-source applications.

Limitations & Caveats

The bot is designed for single-group operation; multiple instances are required for different groups. OpenAI integration incurs costs and requires careful configuration to manage API calls. The effectiveness of spam detection relies on the quality and quantity of training data.