TLG_JoinCaptchaBot is a Telegram Bot designed to verify that new members joining a group are humans by presenting a CAPTCHA challenge.

The bot:

• Automatically sends a CAPTCHA when a new user joins
• Removes users who fail to solve the CAPTCHA within a specified time limit
• Deletes messages containing URLs sent by users who haven't completed the CAPTCHA (anti-spam)
• Block new users to send media messages before the captcha is not solved
• Provides different captcha modes, like visual animated video captchas, image captchas, custom poll captchas, etc
• Has multilanguage support with near to ~30 languages
• Allows custom configuration per group (time for solving the captcha, captcha mode, difficulty, language, welcome message, etc)
• Keeps the groups clean from Bot and captcha messages by automatically self-removing them after a while.

• Requirements
• Installation
• Configuration
• Usage
• Deployment
  • Systemd Service
  • Docker
• Advanced Features
  • Bot Owner Commands
  • Private Mode
  • Scalability (Polling vs Webhook)
• Localization
• Languages Contributors
• Support Development

• Python 3.12+
• Manim requirements
• Pillow requirements
• Telegram Bot Token (from @BotFather)

sudo apt-get install build-essential make python3 python3-dev python3-pip sudo apt-get install libcairo2-dev libpango1.0-dev

sudo apt-get install python3 python3-pip python3-venv

sudo apt update
sudo apt install -y build-essential make libcairo2-dev libpango1.0-dev
sudo apt install -y libtiff5-dev libjpeg62-turbo-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk

git clone https://github.com/J-Rios/TLG_JoinCaptchaBot
cd TLG_JoinCaptchaBot
make setup

Edit the src/settings.py file:

'TOKEN' : 'XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Configuration is handled through the src/settings.json file. Advanced users can also use environment variables, which is useful for deployment scenarios with virtual environments or Docker.

A Makefile is provided for convenient operation:

# View available commands
make

# Start the bot
make start

# Check bot status
make status

# Stop the bot
make stop

To run the bot as a daemon service on systemd-based systems:

1. Create a service file:

sudo nano /etc/systemd/system/tlg_joincaptcha_bot.service

2. Add the following content (adjust paths as needed):

[Unit]
Description=Telegram Join Captcha Bot Daemon
Wants=network-online.target
After=network-online.target

[Service]
Type=forking
WorkingDirectory=/path/to/TLG_JoinCaptchaBot/src/
ExecStart=/path/to/TLG_JoinCaptchaBot/tools/start
ExecReload=/path/to/TLG_JoinCaptchaBot/tools/kill

[Install]
WantedBy=multi-user.target

3. Enable and start the service:

sudo systemctl enable --now tlg_joincaptcha_bot.service
sudo systemctl start tlg_joincaptcha_bot.service

4. Check service status:

sudo systemctl status tlg_joincaptcha_bot.service

Docker support is available for easy deployment and server migration. See the Docker specific documentation for details on creating a Docker container for the bot.

The bot owner can execute special commands:

• /allowgroup: Add groups to the allowed list (when bot is private)
• /allowuserlist: Exempt specific users from CAPTCHA verification (useful for accessibility needs)

Set a bot owner in settings.py:

"BOT_OWNER": "@YourUsername",

By default, anyone can add the bot to any group. To restrict usage to specific groups:

1. Set the bot to private mode in settings.py:

"BOT_PRIVATE": True,

2. Use the /allow_group command to specify permitted groups.

Note: If a public group becomes a supergroup, the chat ID may change, requiring re-authorization.

The bot periodically checks for updates from Telegram servers. This is suitable for small to medium deployments.

The bot receives updates directly from Telegram servers, which improves performance for high-traffic bots.

To configure webhook:

1. Generate SSL certificate:

openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 3650 -out cert.pem

2. Configure webhook settings in settings.py:

"WEBHOOK_IP": "0.0.0.0",
"WEBHOOK_PORT": 8443,
"WEBHOOK_PATH": "/TLG_JoinCaptchaBot",
"WEBHOOK_CERT": SCRIPT_PATH + "/cert.pem",
"WEBHOOK_CERT_PRIV_KEY": SCRIPT_PATH + "/private.key",

3. For reverse proxy setups (optional):

"WEBHOOK_URL": "https://example.com:8443/TLG_JoinCaptchaBot"

4. Enable webhook mode:

"CAPTCHABOT_USE_WEBHOOK": True,

The bot supports multiple languages through external JSON files. To add a new language:

1. Fork the repository and create a new branch (e.g., language-support-xx)
2. Copy an existing language file from the language directory
3. Rename the file to the ISO code of your target language
4. Translate all text values while maintaining:
   • The JSON structure and key names
   • Command names in English (START, HELP, etc.)
   • Special characters ({}, ", ', \n, etc.)
5. Submit a pull request with your translation

• Arabic: @damascene
• Basque: @xa2er
• Belarusian: @antikruk
• Catalán: Adela Casals i Jorba
• Chinese (Mainland): 神林
• Esperanto: Pablo Busto & Porrumentzio
• Finnish: Aminda Suomalainen (@Mikaela)
• French: Mathieu H (@aurnytoraink)
• Galician: Fernando Flores (Fer6Flores); Iváns
• German: @weerdenburg, @MossDerg
• Indonesian: ForIndonesian
• Italian: Noquitt, Nicola Davide (@nidamanx)
• Kannada: @itsAPK
• Korean: @dakeshi
• Persian: @m4hbod
• Portuguese (Brazil): Anahuac de Paula Gil
• Russian: Unattributed (anonymous), @stezkoy, Roman (@toxi22)
• Serbo-Croatian: @IlijaDj
• Slovak: @dumontiskooo
• Ukrainian: Vadym Zhushman (@zhushman00), Roman (@toxi22)
• Uzbek: @mhwebuz

If you find this bot useful, consider supporting the developer:

Paypal: https://www.paypal.me/josrios