chatping_abobot/README.en.md

AboBot

Русский · English

A Telegram bot for group chats. It:

• pings a member when their name comes up in a message or a voice note;
• keeps statistics for the chat and every member;
• fixes text typed in the wrong keyboard layout;
• transcribes and voices messages;
• runs playful events.

The bot speaks Russian.

Status: personal project, running since 2021 · bot @chat_abobot · over 20,000 users from 45 chats in the bot's database (October 2026)

Stack: Python 3.12 · aiogram 3 · pymorphy3 · pyenchant · SpeechRecognition · gTTS · SQLite · Docker

Features

• Name mentions. Words of a message are reduced to their base form (pymorphy3) and compared with members' names, so any grammatical case of a name mentions the right person. A custom name can be set with /edit. Names are also found in voice notes up to a minute long.

• /all mentions every member.

• All-time and monthly statistics (/stat_group, /stat_user): messages, replies, commands, links, media, stickers, voice and video notes. Monthly numbers reset at the start of each month.

• Wrong keyboard layout. A message like ghbdtn is repeated as «привет». English words are recognized with a dictionary (pyenchant) and left alone.

• Voice. /recognize as a reply to a voice note transcribes it; «Озвучь - текст» turns text into a voice note.

• Events:

  • random numbers;
  • reversing text;
  • a language game;
  • mock fights;
  • picture reactions.

  Turned off with /stop_bot.

• Deleting service messages (joins, leaves, title and photo changes) when the bot is an admin.

Running

git clone https://github.com/EDeev/chatping_abobot.git && cd chatping_abobot
cp .env.example .env      # BOT_TOKEN from @BotFather
docker compose up -d

Prebuilt image: docker pull ghcr.io/edeev/chatping_abobot or docker pull dcr.deev.su/edeev/chatping_abobot. The SQLite databases are created on first start.

Without Docker you need Python 3.12, the enchant system library and an English dictionary (apt install libenchant-2-2 hunspell-en-us). Then: pip install -r requirements.txt and cd code && BOT_TOKEN=… python bot.py.

How it works

code/bot.py        entry point and monthly statistics reset
code/handlers.py   message, command, voice and event handlers
code/script.py     statistics, name lookup, keyboard layout, text reversal
code/sql.py        four SQLite databases: groups, users, all-time and monthly statistics
data/              event pictures and the greeting

Member statistics live in a separate table per chat — that is how the bot's production databases are built. Counters are incremented in a single query, so simultaneous messages are not lost. Speech recognition and synthesis (Google Web Speech and gTTS) run in a separate thread, so the bot never freezes.

Development

pip install -r requirements-dev.txt
ruff check --select E9,F,B code tests && pytest

What the tests cover:

• statistics counters;
• mentions and /all;
• the monthly reset;
• keyboard layout, reversal and escaping;
• loading of the bot's handlers.

The Docker image is built on v* tags and published to GitHub Packages and dcr.deev.su.

License

MIT — see LICENSE.

Author

Egor Deev — GitHub · Telegram · egor@deev.space

---

_{⭐ If you find this project useful, give it a star on GitHub!}

_{Made with ❤️ — deev.space}