UA Anti Spam Bot

Intelligent spam protection for Ukrainian Telegram communities

---

UA Anti Spam Bot is a production-grade Node.js bot that detects and removes spam from Ukrainian-language Telegram groups and channels. It combines machine learning models (TensorFlow.js), natural language processing, and rule-based filters to keep communities safe and clean.

Key capabilities

• ML-powered spam detection — TensorFlow.js models trained on Ukrainian-language data
• NSFW image filtering — automatic moderation of inappropriate media
• Swindler & scam detection — pattern-based identification of fraud attempts
• Configurable per-chat — admins can tune every filter through an in-chat menu
• grammY framework — built on the modern, type-safe Telegram bot framework (grammy.dev)

Project Structure

The project is organized into three services and shared infrastructure:

src/
├── bot/              # Grammy Telegram bot service
│   ├── index.ts      # Bot entry point
│   ├── bot.ts        # Bot assembly & middleware chain
│   ├── bot-server.ts # Bot health/admin REST API
│   ├── commands/     # Telegram command handlers (public/ & private/)
│   ├── composers/    # Grammy composers for features & message filters
│   ├── middleware/    # Request processing middleware (parsing, guards, state)
│   ├── filters/      # Boolean filter functions for conditional logic
│   ├── handlers/     # Message & spam processing handlers
│   ├── plugins/      # Custom Grammy plugins (self-destruct, auto-reply)
│   ├── transformers/  # Grammy API call transformers
│   ├── session-providers/ # Redis session storage
│   ├── queries/      # Telegram callback query handlers
│   ├── listeners/    # Event listeners (speech-to-text, tensor training)
│   ├── menus/        # Grammy Menu definitions
│   └── messages/     # Bot response message templates
│
├── server/           # ML API Express server (standalone)
│   ├── index.ts      # Server entry point
│   ├── api.router.ts # REST API routes
│   └── middleware/    # Express middleware
│
├── userbot/          # MTProto userbot for research
│
├── services/         # Shared business logic services
├── tensor/           # TensorFlow.js ML models (spam, swindler, NSFW)
├── dataset/          # Dataset library (imported by app code)
│   ├── dataset.ts    # Main dataset loader
│   └── strings/      # JSON data files
│
├── shared/           # Shared infrastructure
│   ├── config.ts     # Environment configuration
│   ├── db/           # Redis client
│   ├── types/        # TypeScript type definitions
│   ├── const/        # Application constants
│   ├── utils/        # Utility functions
│   └── video/        # Video processing service
│
├── testing/          # Test utilities and mocks
├── locales/          # i18n translation files
└── assets/           # Static assets

dataset/              # Dataset CLI scripts (standalone tools)
│   └── scripts/      # check-swindlers, download, optimize scripts
scripts/              # Developer tooling scripts
tests/                # Vitest test suite (mirrors src/ structure)

Table of Content

• Before you start
  • 1. Files
  • 2. GitHub Access
• Installation
  • 1. Cloning
  • 2. Installing Node.js
    • NVM (recommended)
    • Node
  • 3. Installing Redis
    • Docker-compose (recommended)
    • Install in System
  • 4. Installing node_modules
  • 5. Copy .env file
  • 6. Create your bot
  • 7. Set your Telegram ID
  • 8. Set local testing .env variables
  • 9. Set Google Credits (confidential)
  • 10. Set Alarm Credits (confidential)
  • 11. Copy tensor files
• For external users
  • 1. Disable Google API
  • 2. Disable Alarm API
• Running your bot
  • Enable bot in Telegram
  • Docker
• Code Style
  • Branch names
  • Commit names
  • Code Rules
  • IDE Setup
• Credits

Before you start

If you from Master of Code Global (MOC), PM me for next things:

1. Files

ua-anti-spam-bot-ml-v3.zip
.env.new

2. Github Access

You need to be added into UA Anti Spam Bot Developers team.

Installation

1. Cloning

git clone git@github.com:MoC-OSS/ua-anti-spam-bot.git
cd ua-anti-spam-bot

2. Installing Node.js

NVM (recommended)

If you have Linux or MacOS, it's better to use nvm. We have .nvmrc file which includes the current version of node that we use on the project. Just run the following command at the root of the folder:

nvm use

Node

If you have Windows or want to install Node into the system, find the download Node.js version specified in .nvmrc.

3. Installing Redis

Docker-compose (recommended)

If you have docker and docker-compose, just run the following command:

docker-compose up -d redis

Install in System

If you don't want to use docker-compose, you can install redis in system.

4. Installing node_modules

npm i

5. Copy .env file

Copy .env.template file to .env:

cp .env.template .env

6. Create your bot

Now you need to get BOT_TOKEN from @BotFather. You may find instruction here: https://core.telegram.org/bots/tutorial#obtain-your-bot-token

Set it into .env file:

BOT_TOKEN=4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc

7. Set your Telegram ID

You can ask @RawDataBot to get your ID. Simply write /start and find message.from.id. E.g, it will be 999999999.

Set it into .env file:

CREATOR_ID=999999999

8. Set local testing .env variables

We recommend to set the following variables in your .env file like this:

ENV=local
USE_SERVER=false
DISABLE_LOGS_CHAT=true

9. Set Google Credits (confidential)

You need to obtain your own credits (or ask me if you from MOC team) and set them here:

GOOGLE_CREDITS=
GOOGLE_SPREADSHEET_ID=

10. Set Alarm Credits (confidential)

We use https://alerts.com.ua/ to obtain air raid alarms. You need to ask for a key from the API developer (or me if you from MOC).

ALARM_KEY=

11. Copy tensor files

Extract and copy ua-anti-spam-bot-ml-v3.zip to src/tensor/temp.

For external users

If you are an external user, you need to set the following parameters for the following fields in .env

1. Disable Google API

If you don't have GOOGLE_CREDITS and GOOGLE_SPREADSHEET_ID, you need to specify the value like this:

DISABLE_GOOGLE_API=true

2. Disable Alarm API

If you don't have ALARM_KEY, you need to specify the value like this:

DISABLE_ALARM_API=true

If you're outside the MOC organization, use the copy-swindlers.sh script to copy models from `./src/tensor/swindlers-temp` into the `./src/tensor/temp` destination:

```bash
./copy-swindlers.sh

Running your bot

To start your bot, simply run the following command:

npm run start:bot

Enable bot in Telegram

After it, navigate to your bot and call /start command. If you receive the answer, your bot is working.

Then, try to call /enable command. If you receive the answer, your bot is set correctly and ready to be used.

Test moderation as an admin

If you are a group administrator and want to test moderation without a second Telegram account, use the /role command directly in that group:

/role

This toggles a per-chat test mode for your account only, so the bot will moderate your messages as if you were a regular user. To restore the normal behavior for administrators, run the same command again:

/role

Note: this does not change your real Telegram permissions. Anonymous admins must temporarily disable anonymity before using /role, otherwise Telegram sends the command as GroupAnonymousBot.

Docker

If you want to run the bot via Docker, make sure that you have Docker and Docker Compose installed. Then, run the following command to start the bot in Docker:

docker-compose up --build

Code Style

Branch names

We use branch-name-lint. To push a branch, be sure you have right prefix, ticket name in uppercase, and description split by underscore. Example branch name:

• feature/UABOT-8_create_lp_ui_elements
• hotfix/UABOT-11_add_missing_login_routes

Read more: https://github.com/barzik/branch-name-lint

Commit names

We use Conversational Commits Conversational with commitlint. To make a commit, be sure you follow it. Example:

• feat(UABOT-20): add the users page
• refactor(UABOT-10): refactor tests

Read more: https://www.conventionalcommits.org

Code Rules

We have a pretty heavy eslint and prettier setup, so you don't need to be worried about code style. Tools will make everything for you.

IDE Setup

Don't forget to setup your IDE:

1. WebStorm: Enable eslint plugin in this repo;
2. VSCode: Download and enable eslint plugin in this repo.

Credits

Made with ❤️ to save Ukraine 🇺🇦 2023