tgwatchspam

A self-hosted Telegram bot that protects community groups from spam — crypto offers, job scams, and recruitment messages. Rule-based, predictable, zero cloud dependency.

Самостійно розгорнутий Telegram-бот, який захищає спільноти від спаму — крипто-пропозицій, шахрайства та рекрутингових повідомлень. Правила чіткі, без залежностей від хмари.

Go SQLite Long Polling ~15 MB RAM Self-hosted

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.

tgwatchspam — самостійно розгорнутий фільтр спаму для Telegram-спільнот. Блокує небажані повідомлення про крипту, шахрайство та вакансії. Працює на будь-якому VPS, не потребує веб-інтерфейсу та керується повністю через команди Telegram.

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)

• Linux VPS (будь-який розмір — бот використовує ~15 МБ RAM)
• Токен Telegram-бота від @BotFather
• Ваш числовий Telegram user ID від @userinfobot
• Go 1.21+ (потрібен лише для збірки; бінарний файл самодостатній)

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Створити файл .env

   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_.

   При запуску бот автоматично реєструє всі команди в BotFather, щоб користувачі отримували автодоповнення при введенні /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Розгортання

Build a Linux binary on your local machine, copy it to the server, then create a systemd service so it restarts automatically.

Зберіть Linux-бінарний файл на локальній машині, скопіюйте його на сервер, після чого створіть systemd-сервіс для автоматичного перезапуску.

Cross-compilationКрос-компіляція

No CGO is required — the binary is fully self-contained. Build for any target from any OS:

CGO не потрібен — бінарний файл повністю самодостатній. Збірка для будь-якої платформи з будь-якої ОС:

# Linux AMD64 (most VPS/cloud servers)
# Linux AMD64 (більшість VPS/хмарних серверів)
GOOS=linux GOARCH=amd64 go build -o tgwatchspam-linux ./cmd/bot

# Linux ARM64 (Raspberry Pi, AWS Graviton, etc.)
# Linux ARM64 (Raspberry Pi, AWS Graviton тощо)
GOOS=linux GOARCH=arm64 go build -o tgwatchspam-linux-arm64 ./cmd/bot

# macOS (Apple Silicon)
# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o tgwatchspam-darwin ./cmd/bot

# Windows
# Windows
GOOS=windows GOARCH=amd64 go build -o tgwatchspam.exe ./cmd/bot

Deploy to serverРозгортання на сервері

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

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

Створіть /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.

Кожне вхідне повідомлення проходить триетапний конвейєр:

1. Нормалізація — Кириличні символи, схожі на латинські, замінюються, текст переводиться в нижній регістр.
2. Перевірка слів — Нормалізований текст перевіряється по списку заблокованих слів за принципом підрядка (без меж слів).
3. Перевірка regex — Нормалізований текст тестується по всіх RE2-шаблонах з автоматично доданим (?i).

Word Filtering (FEAT-001)Фільтрація слів (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).

Слова зберігаються нормалізованими. Пошук регістронезалежний і використовує логіку підрядка — доход збігається з доходності, а binance — з binance/bybit (коса риска не розриває збіг).

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

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

Regex Filtering (FEAT-002)Regex-фільтрація (FEAT-002)

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

Шаблони використовують синтаксис RE2 від Go. Прапор (?i) додається автоматично — писати його не потрібно. Приклади шаблонів:

Cyrillic/Latin Normalization (FEAT-003)Нормалізація кирилиці/латиниці (FEAT-003)

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

Спамери обходять фільтри, змішуючи алфавіти — наприклад, пишуть Rоblox з кириличною о. Бот нормалізує це перед перевіркою:

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

1. Користувач вступає → бот повністю обмежує його та публікує повідомлення з кнопкою: "Я не бот — впустіть мене"
2. Натискає кнопку → бот перевіряє, що це та сама людина → видаляє повідомлення верифікації
3. Якщо не натиснув у відведений час → бот автоматично виключає його

/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.

Після верифікації (або одразу, якщо верифікація вимкнена) нові учасники можуть бути поміщені в режим пісочниці. У цьому режимі вони можуть надсилати текстові повідомлення, але не можуть надсилати медіа, стікери, GIF або попередній перегляд посилань.

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

• Верифікація ON + Пісочниця ON — Спочатку натиснути кнопку, потім тільки текст на sandbox_hours
• Верифікація ON + Пісочниця OFF — Натиснути кнопку, потім повний доступ
• Верифікація OFF + Пісочниця ON — Одразу тільки текст, повний доступ після sandbox_hours
• Обидва OFF — Немає обмежень для нових учасників

/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.

Якщо увімкнено, бот перевіряє ім'я та нікнейм нового учасника через ті самі фільтри при вступі. Акаунти на кшталт crypto_earn_fast або usdt_exchanger виключаються до того, як вони щось надішлють.

/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.

Статус адміністратора перевіряється в реальному часі через API Telegram getChatMember при кожному виклику команди — без кешування, без застарілих прав.

Spam LogЖурнал спаму

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

Кожне відфільтроване повідомлення записується в SQLite з повним контекстом: мітка часу, користувач, правило збігу, оригінальний текст повідомлення та вжита дія.

/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.

Один екземпляр бота керує кількома групами одночасно. Всі дані — списки слів, regex-шаблони, налаштування, журнал спаму — повністю ізольовані за chat_id. Дані між чатами не спільні, якщо тільки не скопійовані явно.

# 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.

Усі команди використовують префікс /tgwatch_, щоб уникнути конфліктів з іншими ботами в групі.

Word FiltersФільтри слів

Regex FiltersRegex-фільтри

Spam Action SettingsНалаштування дій для спаму

New Member ControlsКонтроль нових учасників

ManagementУправління

ConfigurationКонфігурація

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

Конфігурація завантажується з файлу .env у робочій директорії.

Per-Chat SettingsНалаштування чату

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

Зберігаються в SQLite і змінюються через команди бота. Кожен чат має незалежні налаштування.

Feature IndexІндекс функцій

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

Кожна функція має тег у коментарях вихідного коду (наприклад, [FEAT-001]). Пошук: grep -r "FEAT-001" .