🤖 Advanced Nub Userbot

A feature-rich Telegram userbot built with Pyrogram, offering a wide range of automation and utility features for power users.

✨ Features

🎵 Music & Entertainment

• Voice Chat Music: Play music in Telegram voice chats with queue support
• YouTube Integration: Search and play music from YouTube
• Audio/Video Support: Handle various media formats
• Queue Management: Add, skip, and manage music queues

📁 File Management

• Auto-Download: Automatically save media from specified channels
• File Tools: Upload, download, and manage files efficiently
• Media Processing: Generate thumbnails and process videos
• Large File Support: Handle files larger than Telegram's limits via external services

🛠️ Utility Tools

• Stats Tracking: Monitor chat statistics and user activity
• Session Management: View and manage active Telegram sessions
• Ping/Uptime: Check bot responsiveness and uptime
• Info Commands: Get detailed user and chat information

🎨 Customization

• Font Styles: Apply various text formatting styles
• Sticker Tools: Create and manage custom stickers
• Profile Management: Clone and revert user profiles
• Custom Responses: Set personalized auto-responses

🔧 Admin Tools

• User Management: Approve/disapprove users, manage whitelists
• Spam Control: Advanced spam detection and prevention
• Message Management: Bulk delete, purge, and moderate messages

🤖 AI Integration

• AI Agent: .ask runs a tool-use loop — the model can search the web, read files, and search the codebase before answering, and remembers the conversation per chat
• Smart Responses: AI-powered text completion and analysis
• Content Generation: Automated writing and summarization

📱 Communication

• Auto-Reply: Intelligent message handling in private chats
• AFK System: Away-from-keyboard status with custom messages
• Broadcast: Send messages to multiple chats simultaneously
• Scheduled Messages: Schedule messages for later delivery

🚀 Quick Setup

Prerequisites

• Python 3.8+
• Telegram API credentials (API ID and Hash)
• Pyrogram session string
• MongoDB database (optional — falls back to in-memory storage if not set)

Installation

1. Get your Telegram API credentials:

   • Visit my.telegram.org
   • Create a new application
   • Note down your API_ID and API_HASH

2. Generate a session string:

   • Use any session string generator for Pyrogram (kurigram)
   • Save the session string securely

3. Configure the bot:

   • Copy .env.example to .env and fill in your credentials
   • At minimum set API_ID, API_HASH, and SESSION_STR
   • Everything else is optional (see Configuration)

4. Install dependencies:

   pip install -r requirements.txt

5. Run the userbot:

   python main.py

   • If SESSION_STR is not set, you will be prompted for a session string
   • The bot will start and load all plugins

Run with Docker

docker compose up -d

The container runs as a non-root user (uid 10001), so downloads and the SQLite store live in named volumes rather than host directories — a bind-mounted host path arrives owned by whoever created it and the container could not write to it. To use host paths instead:

mkdir -p downloads state && sudo chown -R 10001:10001 downloads state
# then swap the volume lines in docker-compose.yml for ./downloads:/app/downloads
# and ./state:/app/state

Pull files out of a volume with docker compose cp userbot:/app/downloads/<name> .. The image sets SQLITE_PATH=/app/state/sessions.db; anything you set in .env still wins, but point it inside /app/state or the store will not survive docker compose up recreating the container.

🚢 Deploy

• A Procfile and app.json are included for easy deployment (see repository root).

⚙️ Configuration

All configuration is done through environment variables (or a .env file). See .env.example for the full list.

Required

• API_ID / API_HASH — Telegram API credentials from my.telegram.org
• SESSION_STR — your Pyrogram session string

Optional

• BOT_TOKEN — bot token from @BotFather, enables inline bot features
• AI_API_KEY — API key for the AI gateway, enables the agentic .ask command and Word Grid vision
• AGENT_MODEL — model the agent uses (default claude-opus-4-8)
• AGENT_VISION_MODEL — vision-capable model for image requests (default claude-opus-4-8)
• AI_BASE_URL — base URL of your Anthropic-compatible gateway; required alongside AI_API_KEY
• AGENT_ALLOW_SHELL — lets the agent run shell commands (default false; see the warning under AI Agent Commands)
• AGENT_FILE_ROOT — directory the agent's file tools may read from (default: the project directory; credential files are refused even inside it)
• AGENT_ALLOW_MODERATION — lets the agent ban/kick/mute/promote members and delete or pin messages (default false; same warning)
• AGENT_ALLOW_TELEGRAM_API — lets the agent call any Telegram client method, not just moderation (default false; supersedes the moderation guards — see the warning under AI Agent Commands)
• YTUBE_API_KEY / YTUBE_BASE_URL — YouTube download service configuration
• MONGO_URI / DB_NAME — MongoDB for persistent storage; leave MONGO_URI empty to use in-memory storage (data is lost on restart)
• GROUP / CHANNEL — your support group and updates channel usernames (without @)

📋 Commands Overview

Basic Commands

• .alive - Check if userbot is running
• .ping - Test response time
• .stats - View comprehensive statistics
• .info [user] - Get user information

Music Commands

• .play <query> - Play audio in voice chat
• .vplay <query> - Play video in voice chat
• .skip - Skip current track
• .vc1 [title] - Start voice chat
• .vc0 - End voice chat

File & Media

• .qt - Create quote stickers
• .kang - Add stickers to pack
• .tiny - Create tiny stickers
• .mmf <text> - Add text to images

Utility Commands

• .clone <user> - Clone user profile
• .revert - Revert to original profile
• .schedule <target> <time> <message> - Schedule messages
• .fonts - Apply text formatting styles

Admin Commands

• .spam <count> <text> - Send repeated messages
• .tagall - Mention all group members
• .purge - Delete message range
• .power <type> - Promote users with permissions

AI Commands

• .ask <question> - Ask the agent; it can search the web, read files, search the codebase, inspect the current chat, and identify a member from a @handle, an ID, or a stylized display name before answering. Reply to a message to pass it along as context.
• .askclear - Forget the agent's conversation memory for this chat (.askreset also works)
• .askmodel - Show the active model and whether the shell, moderation, and full-API tools are armed

Requires AI_API_KEY and AI_BASE_URL. The agent's shell tool is off by default — .ask can embed text from other people's messages into the prompt, so enabling AGENT_ALLOW_SHELL=true turns that text into a command-injection path. Use .eval / .sh to run commands yourself instead.

The file tools (read_file, list_dir, search_files) are not gated behind that flag — the agent needs them to answer questions about the code — so they are sandboxed instead. Every path must resolve inside AGENT_FILE_ROOT (the project directory by default), with symlinks resolved before the check, and files that hold credentials are refused even inside it: .env, .env.* other than .env.example, *.session, the SQLite DB, and key files. search_files is implemented in Python rather than shelling out to grep, so it stays available with shell access off and cannot print a matching line out of a refused file.

Moderation is off by default for the same reason. With AGENT_ALLOW_MODERATION=true the agent can ban, unban, kick, mute, unmute, promote, demote, and set admin titles, and delete or pin the replied-to message — so a message asking to be banned becomes an attack. Even armed, the tools work only in groups where the userbot already holds the matching admin right, never touch the chat owner or the userbot's own account, refuse to ban/kick/mute another admin, never grant can_promote_members, stop after 10 actions per .ask, and log every attempt as [ask-moderation]. Use .ban / .mute / .promote yourself if you would rather decide each one.

Naming a target by display name is resolved conservatively, because that is what decides who an action lands on. A name matches when the query is part of the member's name, or when the member's name lines up with whole words the operator typed — not merely when it falls somewhere inside the query, which used to let a member called "Al" answer a search for "alice". Two members matching means the action is refused and the operator is asked which one. In a chat too large to enumerate, Telegram's own name search runs as well so a second person with that name is not missed, and a lone match from a partial scan is logged as such.

AGENT_ALLOW_TELEGRAM_API=true goes further and lets the agent call any Telegram client method by name — the whole Pyrogram API, not just moderation. This supersedes the moderation guards rather than adding to them: a raw ban_chat_member call bypasses the owner/admin/self refusals and the 10-action cap, and it can act on any chat the account is in, not only the one .ask ran in. What it keeps is a per-run call budget, a result-size cap, an audit line ([ask-api]) per call, and a hard block on session-, login-, lifecycle-, raw-invoke-, payment-, and host-file methods — including a refusal of any argument that names an existing local file, so an uploader cannot be used to post host files out of the account. Treat this as equivalent to handing that person the account, and leave it off unless you mean to.

Those per-.ask caps are caps on the command, not on an attempt. .ask is deliberately not retried as a whole — a retry would replay the entire run with a fresh budget, so a single flood-wait on a status edit could turn a 10-action limit into 40 real bans; only the individual message edits are retried. And the 300s timeout stops the run rather than just stopping the wait: the agent loop checks a cancellation token between steps and before every tool call, so nothing lands after you have been told the request timed out.

⭐ Telegram Premium Features

Some features rely on a Telegram Premium account on the userbot session. They will fail gracefully (raising PremiumAccountRequired) if the account is not Premium:

• Custom Emoji Status: .setemoji <emoji> sets an animated/custom emoji status on your account
• Custom (Animated) Emojis: sending premium custom emojis inside messages
• Voice Chat Streaming: streaming certain media in voice chats may require Premium depending on the chat

No extra configuration is needed — these activate automatically when the session account has Premium.

🛡️ Security Features

• Admin Protection: Prevents actions against configured admins
• Rate Limiting: Built-in flood protection
• User Verification: Whitelist/blacklist management
• Session Security: Monitor and manage active sessions

📝 Customization

Adding Custom Commands

1. Create a new file in the userbot/ or bot/ directory
2. Import required modules and decorators
3. Use @Client.on_message() decorator with filters
4. Implement your command logic

Custom Fonts and Styles

• Modify fonts.py to add new text formatting styles
• Use the .fonts command to apply custom formatting

Auto-Response Settings

• Configure welcome messages for new users
• Set custom AFK messages and responses
• Personalize spam control settings

🔧 Troubleshooting

Common Issues

• Session Errors: Regenerate session string if expired
• Permission Errors: Ensure proper admin rights in groups
• Module Import Errors: Check all dependencies are installed
• Database Connection: Verify MONGO_URI, or leave it empty to use in-memory storage

Performance Tips

• Monitor memory usage for large file operations
• Use appropriate delays for spam prevention
• Regularly clean up temporary files

📄 License

This project is licensed under the MIT License — see the LICENSE file for details. Use responsibly and in accordance with Telegram's Terms of Service.

⚠️ Disclaimer

• This userbot is for educational and personal use only
• Users are responsible for complying with Telegram's ToS
• The developers are not responsible for any misuse
• Some features (custom emoji status, animated emojis) require a Telegram Premium account

🤝 Support

For issues and support:

• Check the troubleshooting section
• Review command documentation
• Ensure proper configuration

---

Note: This userbot includes advanced features that may require technical knowledge to configure and use effectively. Please read all documentation before deployment.