BanAll Telegram Bot

High-speed Telegram bot with two modes:

• Regular users: friendly "chat girl" style conversations in DM and groups.
• Sudo users: instant mass moderation commands (/banall, !banall, /nukeall, !nukeall).

Core Behavior

Regular users

• /start introduces the chat persona (Sukoon).
• Bot chats in private chats and in groups.
• By default, group reply mode is enabled (CHATBOT_GROUP_REPLY_ALL=true).
• Gemini is used for natural responses.
• Sukoon style is tuned for natural Indian Hinglish chat tone.
• If Gemini is slow/unavailable, Sukoon uses a local fallback reply so users still get responses.
• Gemini client now tries fallback models and API versions before local fallback.
• By default, chatbot is enabled for sudo users too (CHATBOT_ALLOW_SUDO=true) so you can test from owner accounts.

Important for groups:

• Disable BotFather -> Group Privacy for your bot, otherwise Telegram will not deliver normal group messages to the bot.

Sudo users

• /banall or !banall: delete command message (if possible), ban actionable members fast, leave group.
• /nukeall or !nukeall: same as above + delete recent messages.
• No second confirmation step.

Repo Layout

• main.py - app startup and handler registration
• config.py - environment config + validation
• handlers/ - moderation/chat logic
• utils/ - Gemini client, logging, guards
• scripts/ - VPS bootstrap, preflight, service install/update helpers
• deploy/systemd/ - systemd service template
• .github/workflows/ci.yml - GitHub CI (compile + tests)

Local Setup

1. Create env file:

cp .env.example .env

2. Create venv + install deps:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

3. Validate config:

python scripts/preflight.py

4. Run:

python main.py

GitHub Push Ready Checklist

1. Ensure secrets are not tracked (.env is ignored by .gitignore).
2. Run tests:

pytest -q

3. Run quick compile check:

python -m compileall main.py handlers utils tests

4. Push branch; CI runs automatically via .github/workflows/ci.yml.

VPS Deployment (Ubuntu)

Step 1: clone on VPS

git clone <your-repo-url> banall-bot
cd banall-bot

Step 2: bootstrap runtime

chmod +x scripts/*.sh
./scripts/bootstrap_vps.sh

Step 3: configure environment

cp .env.example .env
nano .env

Mandatory values:

• API_ID
• API_HASH
• BOT_TOKEN
• SUDO_USERS
• GEMINI_API_KEY (when CHATBOT_ENABLED=true)

Step 4: install systemd service

./scripts/install_systemd_service.sh banall-bot "$(pwd)" "$(whoami)"

Note: deployment from /root/... is supported by default service settings.

Step 5: monitor

sudo systemctl status banall-bot
sudo journalctl -u banall-bot -f

Gemini health check (must show API usage)

After sending a few DM/group messages to the bot:

tail -n 120 logs/actions.log | grep GEMINI_REPLY_SUCCESS
tail -n 120 logs/actions.log | grep CHATBOT_LOCAL_FALLBACK_USED
tail -n 120 logs/errors.log

• GEMINI_REPLY_SUCCESS present = real API replies are working.
• Frequent CHATBOT_LOCAL_FALLBACK_USED means Gemini is failing; check .env key/model values and errors.log.

Fast Update on VPS

After pushing new commits:

cd /path/to/banall-bot
./scripts/update_service.sh banall-bot

Performance Notes

Recommended baseline in .env:

• WORKERS=16
• MAX_CONCURRENT_OPERATIONS=25
• CHATBOT_GROUP_COOLDOWN_SECONDS=1.0 to 1.5
• CHATBOT_GROUP_REPLY_ALL=true

If Telegram flood limits occur, reduce MAX_CONCURRENT_OPERATIONS.

Runtime Dependencies

Production deps are in requirements.txt. Test/dev deps are in requirements-dev.txt.

Legal / Safety

Use moderation commands only where you have authorization and in compliance with Telegram Terms and local law.