TLG_JoinCaptchaBot

Overview

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.

Table of Contents

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

Requirements

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

Installation

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

1. Install Python3 and tools

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

2. Install Pillow & Manim prerequisites

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

3. Get and setup the project

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

4. Configure your Telegram Bot token

Edit the src/settings.py file:

'TOKEN' : 'XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Configuration

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.

Usage

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

Deployment

Systemd Service

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

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.

Advanced Features

Bot Owner

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",

Make Bot Private

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.

Scalability (Polling or Webhook)

Polling (Default)

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

Webhook (For larger 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,

Adding a New Language

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

Languages Contributors

• 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

Donate

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

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