title	antispam.bot
emoji	🛡️
colorFrom	blue
colorTo	indigo
sdk	docker
app_port	8080
pinned	false
license	mit
tags	telegram anti-spam ilang chatbot

🛡️ antispam.bot

The AI guardian that keeps your Telegram groups clean — and actually answers your questions.

Open source (MIT), zero config, self-hostable — the TelegramGuard project.

🌐 English · 中文 · Русский · Español · العربية · فارسی

---

Add it to your group (zero setup)

Add the official bot — no install, no config, no cost.

→ @iLangGuardBot

1. Search @iLangGuardBot on Telegram
2. Add it to your group
3. Give it admin — delete messages + ban users
4. Done. Spam is cleaned automatically; @ it anytime with a question.

You can also DM it directly for AI chat.

---

What it does

🚫 Anti-Spam — Catches ads, scams, crypto & gambling spam. Sees through Unicode lookalikes, full-width and zero-width tricks, emoji stuffing and slang. A zero-cost pre-filter kills the obvious stuff before it ever reaches the AI, and repeat-flooding is caught with no AI call at all.

👁️ Vision — Reads images and video thumbnails to catch image-based ads and QR-code scams. In chat, it reads the story behind a photo, not just the pixels.

💬 Chat — @ it in any group or DM it privately. Multilingual, auto-detects your language. Ask it anything and get a clear, useful answer — factual on sensitive topics, with sensible boundaries on genuinely harmful ones.

---

Self-Host

Bring any OpenAI-compatible AI provider — SiliconFlow (default), OpenAI, DeepSeek, or a local model. You need two things:

• Bot Token — @BotFather → /newbot
• AI API Key — from your provider (default targets SiliconFlow)

Option 1 — VPS (one command)

curl -sL https://raw.githubusercontent.com/ilang-ai/TelegramGuard/main/install.sh | sudo bash

Clones, installs dependencies, prompts for your two keys, and runs as a systemd service. Manage it with:

systemctl status telegramguard     # status
systemctl restart telegramguard    # restart
journalctl -u telegramguard -f     # live logs

Option 2 — HuggingFace Space (free, no server)

1. Fork this repo
2. Create a HuggingFace Space → Docker SDK → Blank
3. GitHub repo → Settings → Secrets → add HF_TOKEN (your HF write token)
4. HF Space → Settings → Secrets → add BOT_TOKEN + AI_API_KEY
5. HF Space → Settings → enable persistent storage so /data (the SQLite DB) is writable — or add a DB_PATH secret pointing somewhere writable
6. Push to GitHub — it auto-deploys to the Space

Option 3 — Manual

git clone https://github.com/ilang-ai/TelegramGuard.git
cd TelegramGuard
pip install -r requirements.txt
cp .env.example .env         # fill in BOT_TOKEN + AI_API_KEY
set -a; source .env; set +a  # load .env into the environment
python bot.py

After creating your bot, send to @BotFather: /setjoingroups → Enable and /setprivacy → Disable (so it can see group messages).

Configuration

Everything is set via environment variables — see .env.example:

Variable	Default	Purpose
BOT_TOKEN	(required)	Telegram bot token
AI_API_KEY	(required)	OpenAI-compatible API key
AI_BASE_URL	https://api.siliconflow.cn/v1	Provider endpoint
AI_MODEL	deepseek-ai/DeepSeek-V4-Flash	Text model
AI_VISION_MODELS	Qwen/Qwen3-VL-30B…	Vision fallback chain (comma-separated)
AI_AUDIO_MODEL	Qwen/Qwen3-Omni-30B-A3B-Instruct	Voice-message model
AI_IMAGE_MAX_WIDTH	600	Downscale width before vision calls
AI_FALLBACK_API_KEY	(empty)	Optional second provider; set to enable a cross-vendor fallback
AI_FALLBACK_BASE_URL	(empty)	Endpoint of that backup provider
AI_FALLBACK_MODEL	(empty)	Text/judge model there
LEXICON_HARD_THRESHOLD	6	Slang pre-filter strictness (higher = stricter)
PROBE_FLAG_DELETE	2	Check-in filler flags before it starts deleting (never bans)
PROBE_WINDOW_HOURS	24	Rolling window for those flags
JUDGE_TEXT_LIMIT	1800	Chars of a long message the judge sees (head + tail)
JUDGE_CAPTION_LIMIT	900	Same, for image captions
GROUP_CMD_COOLDOWN	60	Cooldown (s) on public group commands for non-admins

---

Customize the AI

The bot's brain lives in plain .ilang files — I-Lang Prompt Spec, where each ::GENE defines a behavior.

prompts_demo/
├── persona.ilang     how it thinks + how it talks
├── antispam.ilang    what counts as spam
└── vision.ilang      how it reads images

::GENE_IMMUTABLE{S002, T:RUTHLESS_RED_TEAM, A:FLATTER⇒FAIL, G:ALL, Θ:ALWAYS}
# Show it a plan and it hunts the fatal flaw instead of praising.

::GENE_MUTABLE{P002, T:CONCISE, G:ALL, Θ:ALWAYS}
# 2-3 sentences. Answer first, detail after, zero filler.

::IMMUNE{SPAM, DETECT_THEN_NUKE}
# Ads / scams / flooding → delete + strike, see through evasion.

Change the genes, change the bot. To customize: copy prompts_demo/ to prompts/ (loaded first) and edit.

Learn I-Lang Prompt Spec →

---

Architecture

TelegramGuard/
├── bot.py                 Entry — handlers (group · private · events)
├── config.py              Env config
├── install.sh             One-command VPS installer
├── Dockerfile             Container build
├── modules/
│   ├── ai_provider.py     OpenAI-compatible AI layer (text · vision · audio)
│   ├── chat.py            Prompt orchestration (loads .ilang)
│   ├── prefilter.py       Zero-cost spam pre-filter + triage
│   ├── lexicon.py         Slang / evasion normalization + scoring
│   ├── probe.py           Check-in filler detection (mark-only, never bans)
│   ├── ilang_judge.py     I-Lang decision function
│   ├── admin.py           Group admin
│   ├── db.py              Shared SQLite + async lock
│   └── database.py        Schema
└── prompts_demo/          AI personality (.ilang files)

---

Built with I-Lang Prompt Spec — structured AI instructions as genetic code.

MIT · © iLang Inc. · antispam.bot · ilang.ai