A modular, extensible core for building Telegram bots in Python. It's also a ready-to-use general group management bot.
- Modular architecture: add or remove features as modules.
- Async support (uses
pyTelegramBotAPIasync interface.) - Uses IMY'sDB for file-based JSON storage (or MongoDB,) check the project repo for more details.
- Easy to extend and maintain/
- Show info about users or yourself anytime.
- Custom greetings and farewell messages when a member joins or leaves (can attach pics or videos.)
- Grab and send wallpapers from various sources, including anime-themed ones.
- Reverse search anime pictures to identify the anime.
- Save, list, and remove notes inside the chat.
- Set up automatic keyword triggers that reply with custom messages.
- Manage chat admins. Promote, demote, ban, or unban users.
- Pin important messages.
- Clean up chats by deleting batches of messages at once.
- Toggle and control various bot modules for extra features or disabling unwanted ones.
- Grab media content from Instagram and Twitter/X links.
- Ability to add spoilers to media and text.
- Block sticker sets that are unwanted in the group chat.
- Send an update or news broadcast to everyone who has interacted with the bot, from Telegram (
/broadcast) or the web panel. (Must be owner of bot instance) - Block words or phrases that trigger silent deletion (whole-word, case-insensitive).
git clone https://github.com/IMYdev/YMIcore
cd "YMIcore"
git submodule update --init # pulls IMY-sDB and the LECP-CSS stylesheetpython3 -m venv venv
source venv/bin/activate
cd src/
pip install -r requirements.txtCreate a .env file or set the following environment variables:
BOT_TOKEN=your_telegram_bot_token
LOG_ID=logs_channel_id_without_the_minus
OWNER=your_telegram_id
Optional web panel settings:
WEB_BIND=127.0.0.1 # panel bind address
WEB_PORT=8080 # panel port
WEB_URL=https://your.host # public panel URL (used in /panel login links)
WEB_SECRET=random_secret # optional; a fresh random secret is generated per boot if unset
If self-hosting:
python main.pyYMIcore ships with a browser-based control panel for customizing the bot.
YMIcore Control Panel Instruction Manual
core/ # Core framework logic (database, utils.)
modules/ # All feature modules (filters, notes, etc.)
web/ # Settings web panel (aiohttp server, auth, templates).
botcommands.py # Command router.
main.py # Entry point (bot + web panel).
requirements.txt # Project dependencies.
Each concern has exactly one home. tests/test_structure.py enforces this.
- Storage paths:
core/storage.py. Ask it for anIMYDB(group_db,module_db,groups_db, ...); never build aruntime/...path anywhere else. - Per-group settings:
core/group_settings.py. Notes, filters, stickers, greetings and captcha reads/writes all go through it, for both the bot and the web panel. - Stored replies:
core/replies.py.build_replysaves a replied-to message,send_replysends it (markdown rendered to HTML). - Groups and bans:
core/groups.py, includingban_group_and_leave. - Module toggles:
module_manager.py.is_command_enabled/is_event_enabled/is_module_enabledDefaults live there too, along with the resolution rule and the read cache. - Permissions:
core/utils.py:is_privilegedfor "owner or chat admin",is_owner_idfor a synchronous instance owner check.
-
Add needed environment variables to
.envor your environment. -
Enable/disable features:
- To add a feature, drop a new Python file in
modules/then add a handler call inbotcommands.py, and don't forget to allow the new command in the commands filter inmain.py. - To remove a feature, remove or comment out the relevant handler in
botcommands.pyor the module file.
- To add a feature, drop a new Python file in
-
Write your own modules:
- See
modules/filters.pyormodules/notes.pyfor examples.
- See
- The code is dead simple, written by a simple guy, for people that like simplicity.
- It's fast, trust.
- Does what you need it to do and doesn't get in your way. (hopefully)
- YMI for self-hosted.
This code is licensed under GPLv3 copyleft.
Made with ❤️ by IMYdev.