Telegram group moderation bot with admin-controlled URL blocking, keyword alerts, and EVM address detection.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
$env:TELEGRAM_BOT_TOKEN = "123456:bot-token"
telegram-security-botThe bot stores group settings in data/security-bot.json by default. Override it with SECURITY_BOT_DATA or --data-file.
Add the bot to your group as an admin. It needs permission to delete messages and ban users.
For private alerts, each recipient must open the bot in Telegram and send /start once. Telegram does not let bots initiate private chats with users who have never started them.
/url ON|OFFenables or disables URL restriction. Default: OFF./addurl example.comallows a domain and its subdomains./listurllists allowed URL domains./delurl example.comremoves an allowed domain./alert ON|OFFenables or disables keyword alerts. Default: OFF./addreceiver @usernameadds an alert recipient./listreceiverlists alert recipients./delreceiver @usernameremoves an alert recipient./addkeyword Metaadds a watched keyword./listkeywordlists watched keywords./delkeyword Metaremoves a watched keyword./scandelaccscans known group members and removes deleted Telegram accounts./delca ON|OFFremoves users when they join with an EVM-like address in their displayed name. Default: OFF./sendca ON|OFFdeletes messages containing EVM-like addresses. Default: OFF./warningmsg ON|OFFenables or disables scheduled warning messages. Default: OFF./warningtxt messagesets the warning message text./warningfreq secondssets how often the warning is sent. Default: 600 seconds./warnmediaadds media to warning messages by replying to an image, GIF, or video.
Group admins are always allowed to send URLs. Only group admins can change bot settings.
Keyword alerts trigger on joins, on messages from a user whose display name changed, and on a periodic scan of users the bot has already seen in the group. The scan interval defaults to 60 seconds and can be changed with SECURITY_BOT_NAME_SCAN_SECONDS.
/scandelacc can only scan users the bot already knows from joins or messages. Telegram Bot API does not provide bots with a full group member list.
For /warnmedia, first send the image, GIF, or video in the group, then reply to that media message with /warnmedia. Telegram file IDs are stored, not downloaded media files.
Before each scheduled warning is posted, the bot deletes the previous warning message it sent in that group.
/warningtxt preserves new lines and Telegram text formatting such as bold, italic, links, and code. For multi-line warnings, send the command like this:
/warningtxt First line
Second line
Third line