Telegram-KickMi-Bot-2

IMPORTANT NOTE: This is all still very buggy and designed for my personal use

A Telegram-Bot to which monitors a group he's invited to and schedules all new users to solve a challenge. Without solving the challenge the user is not allowed to post in the group and will be kicked after a defined time.

Features

• monitor several Telegram-Groups
• automute new group users
• challenge user for
  • a random word from a wordlist
  • solve a simple math question (addition or multiplication)
• kick user after a defined time if he hasn't solved the challenge
• unmute the user after solving his challenge

Installation

Install uv (and Python, if needed) by following the official docs:

• uv installation

On Debian/Ubuntu you can install Python via apt:

apt install python3

Get bot running:

# copy this repo
git clone https://git.univ-exp.com/stefan/Telegram-KickMi-Bot-2.git
cd Telegram-KickMi-Bot-2

# install with uv
uv sync

# export BOT_API_TOKEN
export BOT_API_TOKEN=your_token_here
export BOT_ADMIN_PASSWORD=your_password_here
# run bot
uv run python -m telegram_kickmi_bot_2

Docker

Environment Variables

Create a .env file in the root directory by running these commands:

# Create .env file with mandatory bot token (replace your_token_here!)
echo "BOT_API_TOKEN=your_token_here" > .env
echo "BOT_ADMIN_PASSWORD=your_password_here" >> .env
# Add UID/GID
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env

Note: The BOT_API_TOKEN is mandatory for the bot to function. You can get it by talking to @BotFather on Telegram. Note: The BOT_ADMIN_PASSWORD is mandatory for the bot to function. It is used to activate the bot in the groups.

Docker Compose

You can run the bot using Docker Compose. First, make sure you have Docker and Docker Compose installed on your system.

1. Create the .env file as described above

2. Use the repository's compose.yml file:

3. Start the bot:

docker compose up -d

The bot will automatically restart unless stopped manually. You can view the logs with:

docker compose logs -f

To stop the bot:

docker compose down

Usage

Just invite the bot to your Telegram-Group. Make sure to give him the rights to Block users and that he has the rights to read group-messages. Then run /start in the group to activate the bot and provide the bot-admin password. If the rights are missing you'll get an information for the groups missing rights. Change the rights of the bot and run /start again to activate the bot in the groups.

You can check the rights of the bot with /check.

Without any right to Block users you'll get an information in the group about missing rights.

Commands

The bot supports the following commands:

• /help - Shows help information about the bot and available commands
• /start - Activates the bot in the groups
• /check - Checks the rights of the bot in the groups
• /id - Shows your Telegram user ID (useful for whitelisting)
• /schedule - Lists currently scheduled users pending verification (admin only)
• /info - Shows how many users have been blocked by the bot in the current group (admin/whitelist)

Note: The bot will send help and schedule information via private message. Make sure to start a private chat with the bot first. /info responds in the group.

Admin Configuration: Administrators can whitelist users by adding their Telegram user IDs to the configuration file. Whitelisted users will not need to complete verification challenges.

Configuration

Bot Configuration

The bot's configuration is stored in ./config/config.toml. Here's an example configuration:

log_level = "INFO"    # log level, default "INFO" ('CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG')
group_ids = [         # list of group ids to monitor (int)
    -1234567890,      # group id might be negative
]

Group Configuration

Each group's configuration is stored in ./config/groups/group_$GROUP_ID.toml, where $GROUP_ID is the Telegram group ID. Here's an example configuration:

# Basic group information
group_type = "supergroup"   # Type of group (supergroup or group)
group_id = -1234567890   # Telegram group ID
group_title = "bottest"     # Group name
activated = false           # Whether the group is activated
kicked_users_count = 0      # Counter: users blocked by the bot in this group

# Challenge settings
challenge_type = "word"      # Type of challenge ("word" or "calculation")
challenge_time_s = 1800      # Time in seconds to solve the challenge, default 30 minutes
whitelist = []               # List of whitelisted user IDs

# Currently scheduled users
scheduled_users = []          # Users pending verification

# Wordlist configuration for word challenges
[[wordlists]]
language_code = "en"
wordlist_path = "/path/to/wordlist_en.txt" # will be filled with the default wordlist

The configuration file is automatically created when the bot is added to a group. You can modify these settings manually to customize the bot's behavior for each group.

Note: After modifying the configuration, you'll need to restart the bot for changes to take effect.

Developer guides

Code Style

We use the Google Python Code-Style, especially for the Docstrings.

Pre-Commit Hooks

We use pre-commit to enforce the following code style, linting and formatting. We use ruff and pre-commit to lint the code.

# install pre-commit, and ruff
uv tool install pre-commit
uv tool install ruff

# install pre-commit hooks
pre-commit install

From now on, the pre-commit hooks will run before every commit.

Assets

• "kick" by Gan Khoon Lay from the Noun Project

License

Author Stefan Maier Licence GNU GPLv3

Contributing

Bug reports and pull requests are welcome on my website or mail to git@univ-exp.com