USERGE-X

A powerful, pluggable Telegram UserBot built with Python and Pyrogram.

Note: This is an archived project from my early coding days. It is no longer actively maintained.

---

Overview

USERGE-X is an extensible Telegram UserBot that provides a modular plugin architecture for automating tasks, managing groups, and adding custom functionality to a Telegram account. It supports both user-mode and bot-mode (dual-mode) operation, with a built-in plugin system that makes it straightforward to extend.

Tech Stack

Category	Technology
Language	Python 3.8+
Telegram MTProto	Pyrogram (custom fork)
Database	MongoDB (via Motor — async driver)
Cloud Storage	Google Drive API
Deployment	Docker, Heroku
Shell Scripting	Bash (init, bootstrap, logging)

Architecture

userge/
├── core/ # Client, database, raw Pyrogram extensions
│ ├── ext/ # Connection pooling, raw client wrapper
│ ├── methods/ # Chat, decorator, message, user, and utility methods
│ └── types/ # Bound messages, filters, commands, plugin manager
├── plugins/ # Modular command plugins
│ ├── admin/ # Anti-flood, bans, locks, purge, warns
│ ├── bot/ # Alive checks, PM guard, inline helpers
│ ├── fun/ # Meme generation, stickers, carbon, quotes
│ ├── misc/ # Downloads, uploads, Google Drive, YouTube, RSS
│ ├── tools/ # Executor, system info, updater, search
│ └── utils/ # Filters, notes, translate, weather, AFK
├── utils/ # Shared helpers — aiohttp, progress bars, exceptions
└── xcache/ # Caching layer

Key Features

• Plugin System — Hot-loadable plugins with command and filter decorators; each plugin is self-contained with its own help text.
• Dual Mode — Operates simultaneously as a userbot and an inline bot.
• Group Administration — Anti-flood, global bans/mutes, permission locks, warn system.
• Media Tools — Google Drive upload/download (Team Drives supported), YouTube download, Telegram file split/combine, archive handling (zip/tar/rar).
• Utilities — OCR, translate, weather, dictionary, currency conversion, COVID stats, speed test, web screenshots.
• Conversation API — Async conversation handler for interactive multi-step flows within chats.
• Channel Logging — Structured logging to a dedicated Telegram channel.
• Database-Backed State — Persistent configuration, notes, filters, and permissions via MongoDB.

Plugin Example

fromusergeimportuserge, Message, filtersLOG=userge.getLogger(__name__)
CHANNEL=userge.getCLogger(__name__)
@userge.on_cmd("test", about="Run a quick diagnostic")asyncdeftest_cmd(message: Message):
LOG.info("starting test command...")
awaitmessage.edit("testing...", del_in=5)
awaitCHANNEL.log("testing completed!")
@userge.on_filters(filters.me&filters.private)asyncdefecho_filter(message: Message):
awaitmessage.reply(f"you typed - {message.text}", del_in=5)
awaitCHANNEL.log("filter executed!")

Getting Started

Prerequisites

• Python 3.8+
• Telegram API credentials
• MongoDB instance
• (Optional)Google Drive API credentials

Local Setup

# Clone and enter the project
git clone https://github.com/sh-himanshu/USERGE-X.git
cd USERGE-X
# Create a virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp config.env.sample config.env
# Edit config.env with your API_ID, API_HASH, DATABASE_URL, etc.# Generate a string session
bash genStr
# Run
bash run

Docker

docker-compose -f resources/docker-compose.yml up --build

Credits

• Pyrogram — Telegram MTProto API framework
• Motor — Async MongoDB driver
• Google API Python Client