DOCSEARCHbyAlgolia
Submit Docs

UserGe Documentation

website·Indexed 29 days ago

https://userge-docs.vercel.app/

Documentation for the UserGe userbot, including setup guides for Heroku, Docker, and Termux, plugin development using custom callback decorators like @userge.on_cmd, and troubleshooting common Pyrogram session errors.

Tokens
6.1K
Snippets
36
Records
55
Agent score
75%

What's inside UserGe

  1. Overview of UserGe Telegram UserBot

    UserGe is a powerful, pluggable Telegram UserBot written in Python using the Pyrogram library. It allows users to automate their Telegram accounts through a variety of built-in plugins and commands. Key features include:

    • Telegram and Google Drive (including Team Drive) upload/download support
    • Archive management (Zip, Unzip, tar, Split/Combine)
    • Account management tools: PM Permit, AFK, Notes, Filters, and Welcomes
    • Advanced utilities: OCR image reader, background removal APIs, and group management
    • Integrated plugin manager and built-in help system (accessible via .help)

  2. Create a custom command plugin in UserGe

    To create a custom command in UserGe, use the @userge.on_cmd decorator. This decorator takes the command trigger string as the first argument and an optional about parameter to provide help text for the command. The handler function must be asynchronous and accept a Message object.
    from userge import userge, Message

@userge.on_cmd("test", about="help text to this command")
async def test_cmd(message: Message):
   # Perform actions
   await message.edit("testing...")

  3. Configure @userge.on_cmd parameters and access controls

    The @userge.on_cmd decorator accepts several parameters to control command behavior, visibility, and permissions.

    Mandatory Parameters:

    • command (str): The command name without the trigger prefix.
    • about (str | dict): Description for help strings. If a dictionary, it can contain: header, description, flags, options, types, usage, examples, others, and wild card. Use {tr} in usage/examples to represent the user's configured command trigger.

    Optional Parameters:

    • trigger (str): Custom trigger prefix (Defaults to Config.CMD_TRIGGER).
    • prefix (str): Custom prefix for flags (Defaults to '-').
    • filter_me (bool): If True, only the owner and sudo-users can access the command. If False, everyone can access it. (Default: True)
    • allow_private, allow_bots, allow_groups, allow_channels (bool): Enable or disable the command in specific chat types. (Default: True)
    • only_admins (bool): Requires admin privileges in the chat. (Default: False)
    • del_pre (bool): If True, message.flags will be a dictionary without the prefix. (Default: False)

    Permission Checks (Boolean): Passing True to these parameters ensures the client has the required permission before executing the function:

    • check_change_info_perm, check_edit_perm, check_delete_perm, check_restrict_perm, check_invite_perm, check_pin_perm.
    @userge.on_cmd(
    "echo", 
    about={"header": "Echo"},
    allow_private=False, 
    allow_channels=False, 
    allow_bots=False, # Only works in groups
    trigger='>',       # Custom trigger prefix
    prefix='*',        # Custom flag prefix
    filter_me=False    # Accessible by all users
)
async def echo(message: Message):
    # ... function body

  4. Handle command flags and replied messages in Userge

    Userge allows defining flags within the about dictionary of @userge.on_cmd. These flags are accessible via message.flags during execution. This is useful for altering command behavior, such as switching input sources to a replied message.
    from userge import userge, Message

@userge.on_cmd("echo", about={
    'header': "Echo",
    'description': "Give any text i will repeat it",
    'flags': {'-r': "I will take text from replied message if u send command with this flag"},
    'usage': "{tr}echo [flag (optional)]",
    'examples': ['{tr}echo Hi', '{tr}echo -r']})
async def echo(message: Message):
    text = message.input_str
    # Check if the -r flag was passed and a reply exists
    if '-r' in message.flags and message.reply_to_message:
        text = message.reply_to_message.text
    
    if text:
        await message.client.send_message(message.chat.id, text)

  5. Add official plugins to UserGe

    After starting your Userbot, you can add the official Userge-Plugins repository using the .addrepo command.
    .addrepo https://github.com/UsergeTeam/Userge-Plugins

  6. Configure Google Drive integration

    To set up Google Drive for file uploads:

    1. Send .gsetup in your Userge Log channel.
    2. Click the provided OAuth link, authorize the account, and copy the resulting code.
    3. Send .gconf {your_copied_code} in the log channel.
    4. To specify the upload folder, find the Folder ID from the Google Drive URL (the string of characters after id= or folders/) and send .gset {your_parent_id}.
    5. Use .gup to upload files.
    .gsetup
.gconf <auth_code>
.gset <folder_id>
.gup

  7. Configure MongoDB DATABASE_URL

    Userge requires a MongoDB database for storage. Follow these steps to set up a free cluster on MongoDB Atlas:

    1. Sign up/login at cloud.mongodb.com.
    2. Build a Cluster: Select the Free plan, choose a region/server nearest to your location, and click Create Cluster.
    3. Network Access: Under the Security section, go to Network Access -> Add IP Address and select Allow Access From Anywhere.
    4. Database User: Go to the Cluster option, click Connect, and create a MongoDB user with a username and password (avoid special characters like @#$%).
    5. Connection String: Select Connect Your Application, set the Driver to Python and Version to 3.6 or later.
    6. Copy the connection string and replace <password> with your actual password and myFirstDatabase with test or cluster0.
    mongodb+srv://<username>:<password>@mongos0.example.com/test?retryWrites=true&w=majority

  8. Manually install Userge on Termux step-by-step

    If the quick setup is not used, follow these manual steps to install Userge. This involves updating packages, installing the root repository, setting up Python and dependencies (including a specific build for Pillow), cloning the Loader repository, and configuring the environment variables.
    # Update packages and install root repository
pkg update && pkg upgrade
pkg install root-repo

# Install Python and system dependencies
pkg install git python proot resolv-conf libxml2 libxslt libjpeg-turbo
pip install -U pip wheel setuptools

# Install Pillow with specific flags for Termux
LDFLAGS="-L/system/lib/" CFLAGS="-I/data/data/com.termux/files/usr/include/" pip install Pillow

# Clone the Loader repository
git clone https://github.com/UsergeTeam/Loader Loader && cd Loader

# Install requirements
bash install_req

# Setup configuration
cp config.env.sample config.env
nano config.env

# Run Userge
termux-chroot
cd Loader
bash run

  9. Unpack and unzip files in UserGe

    To extract files, first download the file using .download to get the file path, then use the .unpack command with that path.
    .download <url>
.unpack downloads/filename.zip

  11. Obtain Telegram API_ID and API_HASH

    To configure the Userge Userbot, you must obtain an API_ID and API_HASH from Telegram:

    1. Log in to my.telegram.org using your phone number.
    2. Navigate to the API Development Tools section.
    3. Create an application by entering an App name and App short name. Use my.telegram.org in the URL section.
    4. Copy the resulting API_ID and API_HASH for use as environment variables.

  12. Deploy Userge to Heroku

    To deploy Userge to Heroku, fork the Helper Script repository and rename the fork with a random name. Use the following URL format to deploy the application to your Heroku account.
    https://heroku.com/deploy?template=https://github.com/username/repo_name