tgwatchspam

Overview

tgwatchspam is a self-hosted spam filter for Telegram community groups. It blocks unwanted messages about crypto, job scams, and other common spam patterns. Runs on any private VPS, requires no web interface, and is managed entirely through Telegram commands.

Setup

Requirements

• A Linux VPS (any size — the bot uses ~15 MB RAM)
• A Telegram bot token from @BotFather
• Your numeric Telegram user ID from @userinfobot
• Go 1.21+ (only needed to build; the binary is self-contained)

First Run

1. Clone and build

   git clone https://github.com/sqerison/tgwatchspam
   cd tgwatchspam
   go build -o tgwatchspam ./cmd/bot

2. Create your .env file

   cp .env.example .env
   # Edit .env and fill in BOT_TOKEN and SUPERADMIN_ID

3. Run the bot

   ./tgwatchspam

   On startup the bot automatically registers all commands with BotFather so users get autocomplete when typing /tgwatch_.

4. Add the bot to your group

   Grant it admin rights with: Delete messages, Ban users, Restrict members.

5. Verify it works

   /tgwatch_show settings

   The bot should reply with the default settings for your chat.

Deployment

Copy the binary and .env to the server, then create a systemd service so it restarts automatically.

scp tgwatchspam .env user@yourserver:/opt/tgwatchspam/

Create /etc/systemd/system/tgwatchspam.service:

[Unit]
Description=tgwatchspam Telegram bot
After=network.target

[Service]
WorkingDirectory=/opt/tgwatchspam
ExecStart=/opt/tgwatchspam/tgwatchspam
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl enable --now tgwatchspam
journalctl -u tgwatchspam -f   # view live logs

Spam Filtering

Every incoming message passes through a three-stage pipeline:

1. Normalize — Cyrillic lookalike characters are mapped to their Latin equivalents and the text is lowercased.
2. Word match — The normalized text is checked against the blocked word list using substring matching (no word boundaries).
3. Regex match — The normalized text is tested against all RE2 patterns with (?i) prepended automatically.

Word Filtering (FEAT-001)

Words are stored normalized. Matching is case-insensitive and uses substring logic — доход matches доходності, and binance matches binance/bybit (the slash does not break the match, fixing the main flaw of the previous bot).

/tgwatch_add word bitcoin
/tgwatch_add word гарна плата

# Bulk import — one word per line:
/tgwatch_add word
bitcoin
usdt
крипта
заробіток
digital nomad

Regex Filtering (FEAT-002)

Patterns use Go's RE2 syntax. The (?i) flag is added automatically — you do not need to write it. Example patterns:

Cyrillic/Latin Normalization (FEAT-003)

Spammers bypass filters by mixing scripts — for example writing Rоblox with a Cyrillic о. The bot normalizes these before matching:

Spam Actions

When a message matches a filter, the bot takes a configurable action. The message is always deleted first.

/tgwatch_set action ban
/tgwatch_set action mute
/tgwatch_set mute_duration 24    # hours, used when action=mute

After every spam detection the bot posts a notification in the group:

New Member Controls

Button Verification (FEAT-015)

When enabled, new members must tap an inline button before they can post anything. This stops the vast majority of bot accounts that join and immediately post spam.

Flow:

1. User joins → bot fully restricts them and posts a public message with a button: "I'm not a bot — let me in"
2. User taps the button → bot verifies it's the same person → removes the verification message
3. If they don't tap within the timeout → bot kicks them automatically

/tgwatch_set verification on
/tgwatch_set verification_timeout 5    # minutes before auto-kick (default: 2)

Sandbox Mode (FEAT-007)

After passing verification (or immediately if verification is off), new members can be placed in sandbox mode. During sandbox they can post regular text messages but cannot send media, stickers, GIFs, or link previews.

Sandbox and verification work together:

• Verification ON + Sandbox ON — Must tap button first, then text-only for sandbox_hours
• Verification ON + Sandbox OFF — Must tap button, then full access
• Verification OFF + Sandbox ON — Text-only immediately, full access after sandbox_hours
• Both OFF — No restrictions on new members

/tgwatch_set sandbox on
/tgwatch_set sandbox_duration 24    # hours (default: 24)
/tgwatch_unrestrict                 # reply to a user's message to lift sandbox early

Name Filter (FEAT-010)

When enabled, the bot runs a new member's display name and username through the same word/regex filters on join. Accounts like crypto_earn_fast or usdt_exchanger are kicked before they post anything.

/tgwatch_set name_filter on

Admin Authorization

All management commands require the user to be a group admin. Non-admins who send commands are silently ignored — no error reply, no indication that the command was received. This avoids tipping off spammers.

Admin status is verified live via Telegram's getChatMember API on every command call — no caching, no stale permissions.

Spam Log

Every filtered message is recorded in SQLite with full context: timestamp, user, matched rule, original message text, and action taken.

/tgwatch_log            # last 10 entries
/tgwatch_log 25         # last 25 entries (max 50)
/tgwatch_log clear      # clear the log for this chat (inline button)

Multi-Chat Support

One bot instance manages multiple groups simultaneously. All data — word lists, regex patterns, settings, spam log — is completely isolated per chat_id. No data is shared between chats unless explicitly copied.

# Superadmin only, send this in a DM with the bot:
/tgwatch_copy -100123456789 -100987654321

The bot will ask for confirmation before overwriting. Existing data in the target chat is replaced, not merged.

Command Reference

All commands use the /tgwatch_ prefix to avoid conflicts with other bots in the same group.

Word Filters

Regex Filters

Spam Action Settings

New Member Controls

Management

Configuration

Configuration is loaded from a .env file in the working directory.

Per-Chat Settings

These are stored in SQLite and changed via bot commands. Each chat has independent settings.

Feature Index

Each feature has a tag in source code comments (e.g. [FEAT-001]). Search with grep -r "FEAT-001" .

tgwatchspam — self-hosted, open source, written in Go. github.com/sqerison/tgwatchspam