eGenix Antispam Bot for Telegram
eGenix Antispam Bot for Telegram
This bot package provides a simple, yet effective way to deal with spam signups to Telegram Messenger (TG) groups. Unfortunately, these have grown to a level that is not manually manageable anymore (see Motivation below for details).
- Low impact mode of operation: the bot tries to keep noise in the group to a minimum
- Several challenge mechanisms to choose from, more can be added as needed
- Flexible and easy to use configuration
- Only needs a few MB of RAM, so can easily be put into a container or run on a Raspberry Pi
- Can handle quite a bit of load due to the async implementation
- Python 3.9+
- pyrogram package (see requirements.txt)
- only tested on Linux
In order to run the bot and connect it to your TG group(s), you will first have to get API tokens from TG. Please see https://core.telegram.org/api/obtaining_api_id#obtaining-api-id for details on how to obtain the two credentials API ID and hash.
⚠️ The API credentials are bound to the TG account you create them with and can be used to even delete the account, so keep them safe.
Next, you need to register a bot with TG. This can be done by chatting with the TG BotFather. See https://core.telegram.org/bots#3-how-do-i-create-a-bot for details. The BotFather will send you a Bot token.
It is best to install the bot inside a venv. You can use the virtual env tool of your choice to set this up.
Then install the package, using pip:
pip3 install telegram_antispam_bot
Installation using Docker
If you want to run the bot using Docker, have a look at the
subdir in the source distribution. After configuring the bot in
docker/config/tgbot_env you can then run the bot by running:
cd docker/ docker-compose up -d
Be sure to check the logs using
docker-compose tgbot logs for any
errors that may occur. You can also without "-d" (no detach) to see the
logs written to the console for testing purposes.
The simplest way to configure the bot is via OS environment variables
(env vars), but you can also put the configuration into a Python module
local_config.py which Python can find on the sys.path. See
telegram_antispam_bot/config.py for details.
We'll go with the env var approach. All env vars use the prefix "TG_" to avoid getting in the way with other env vars.
The most important variables to set are these:
TG_API_ID: Use the API ID you received from TG.
TG_API_HASH: Use the API hash you received from TG. This is secret information.
TG_BOT_TOKEN: Use the Bot token you received from the BotFather. This is secret information.
TG_SESSION_NAME: Session database name to use. Defaults to 'antispambot'. You only need to set this in case you plan to run multiple bot instances from the same directory.
Limiting the attack surface
You only need to pass in the real values of the authentication env vars when first authenticating against the TG API.
The underlying pyrogram package will store the session credentials in a
SQLite database (named after
Once this is in place, the secrets can be replaced with dummy values or left unset. Do take care to protect the session database, since this can be used to hijack TG sessions. The bot will enforce file permissions upon startup.
You can also specify a few other env vars to further customize the installation:
TG_MANAGEMENT_GROUP_ID: Set this to the TG ID of the group you want to use for receiving admin log messages. The bot will have to be made member of this group. The bot will always log these messages to stdout.
TG_MODERATION_GROUP_IDS: Set this to a comma separated set of group IDs to moderate. If not set, the bot will moderate all groups it gets added to as an admin.
TG_DEBUG: Set this to 1 to get debug messages, which will include details about the messages sent to chats the bot is listening on.
TG_CHALLENGES: Set this to a comma separated list of Challenge subclass names found in
telegram_antispam_bot/challenge.py. The bot will then pick one of these randomly when sending a challenge.
Getting the group IDs is not easy from the TG clients, but you can use
TG_DEBUG setting to find out the IDs. The log will show entries
chat=pyrogram.types.Chat(id=1234, type='supergroup', ... when writing messages into the group chat. In this example, the
group ID to use is 1234.
It is usually best to configure the extra settings after getting the initial setup up and running.
For more details regarding the configuration and more settings, please
have a look at the
Running the Bot
You can run the bot inside a container, as a service on a root server or VM, or manually from the command line.
If you've setup the configuration via OS environment variables, all you need to do is run the package:
python3 -m telegram_antispam_bot
Adding the Bot to a TG Group
In order for the bot to work on a group, you will have to add it as an admin to the group. It needs the permissions Delete messages and Ban users. The other permissions can be disabled.
Unlike other TG bots, this bot does not implement any bot commands (e.g. there is no '/help').
Experience has shown that implementing such commands often leads to group members trying to interact with the bot, even though they don't have permission to do anything. This usually creates enough noise to make the bot operation less useful.
How it works
The bot will recognize new group signups and ask the new users to enter a challenge string within a certain time frame. Correctly entering the challenge then accepts the new user. Not entering the challenge in time results in a ban. The same happens, if the user enters too many wrong answers.
The bot / user conversation is mostly deleted after either successful or failed signup to keep the noise level low.
I see connection error messages in the logs. Are those something to worry about ?
No, the underlying pyrogram library will automatically try to reconnect. You should only dig deeper in case you notice that the bot is not reacting to new signups.
I changed the configuration. Will the bot automatically detect those changes ?
No, you will have to restart the bot for the changes to take affect.
Will restarting the bot have a negative effect ?
A short downtime is not much of a problem. If you restart the bot while it is talking to a new signup, you will have to do manual cleanup of the chat, since the conversations are not stored in the database.
I don't want to monitor a log file. Can I point the bot to an admin TG group ?
Yes, you can set up a TG admin group, make the bot a (regular) member and then add the ID of the group as
eGenix has long been running a local user group meeting in Düsseldorf called Python Meeting Düsseldorf and we have been using a Telegram group for group communication.
In the early days, the group worked well and we only had few spammers joining it, which we could well handle manually. More recently, this has changed dramatically. We are seeing between 2-5 spam signups per day, often at night. Furthermore, the signups accounts are not always easy to spot as spammers, since they often come with profile images, descriptions, etc.
With the bot, we now have a more flexible way of dealing with the problem.
Credits / Notices
Thanks go out to Dan for creating the wonderful pyrogram async TG package.
"Telegram" is a trademark of Telegram LLC.
- Added new challenge MathMultiplyChallenge
- Made the MathAddChallenge and MathMultiplyChallenge a little more difficult
- Added new challenge ListItemChallenge
- Added new config variables MAX_FAILED_CHALLENGES to limit the number of failed challenge responses. Defaults to 3.
- Added docker-compose config example to sources
- Fixed display of the user name to always show the full name, where available.
- Added work-around for pyrogram to not create session files inside the package dir when running the bot in -m mode
- Fixed bug to make file logging work
- Fixed bug in ban time handling; this now works correctly
- 0.2.0: Initial release on PyPI
- 0.1.0: Initial release on Github
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for egenix-telegram-antispam-bot-0.4.0.tar.gz
Hashes for egenix_telegram_antispam_bot-0.4.0-py3-none-any.whl