Ether Userbot System

The Next-Gen Modular Telegram Framework

Ether is a high-performance, modular Telegram userbot architecture built with Telethon and PyMongo Async. Designed for developers who prioritize security, sovereignty, and scalability.

---

Repository Statistics

---

Features • Structure • Configuration • Deployment • Commands • Development • Contributors

---

Sovereignty & Security

Ether is engineered to eliminate the most common security risks in the userbot ecosystem.

• Zero String Session Reliance: No third-party bots or risky session generators. Ether uses the official Telegram native authentication flow.
• Direct Auth: Use the /login command to trigger an official Telegram OTP/2FA flow directly to your device.
• Encrypted Storage: Your session data is stored securely on your server. It never touches a developer's database or public logs.
• No Middleware Risks: Your credentials remain private. No Replit, no external middleware, just direct communication with Telegram servers.

---

Key Features

• Hybrid Engine: Orchestrates Telethon (Userbot) and Telegram Bot API concurrently for maximum flexibility.
• Plug-and-Play: Drop any .py script into the plugins/ directory to instantly extend functionality.
• Native Async: Fully asynchronous architecture powered by pymongo native async drivers for high-concurrency handling.
• Health Monitoring: Integrated FastAPI heartbeat service for 100% uptime on cloud providers.
• Containerized: Production-ready Docker configuration for seamless local or cloud orchestration.

---

Repository Structure

Ether follows a clean, modular directory structure for scalability and ease of development.

Ether/
├── assets/             # Static media and branding
├── config/             # Environment and global configuration
├── core/               # The engine: Userbot, Bot API, and Loader
├── logs/               # Persistent system and session logs
├── plugins/            # Add-on functionality (.py files)
├── services/           # Logic layers for database interactions
├── storage/            # MongoDB connection management
├── utils/              # Shared helpers and logging tools
├── main.py             # Main entry point for the hybrid system
└── web_service.py      # FastAPI heartbeat service

---

Tech Stack & Dependencies

Ether is built on a modern, high-performance stack designed for low latency and high concurrency.

Technology	Purpose
Python 3.11+	Core programming language
Telethon	MTProto library for Telegram User & Bot API interaction
PyMongo Async	Native asynchronous driver for MongoDB
FastAPI	High-performance web framework for health monitoring
Uvicorn	ASGI server for production-grade web service
Docker	Containerization and environment isolation
python-dotenv	Environment variable management

---

Configuration

Caution

Security Warning: Never expose your environment variables or upload your .env file to public repositories. Anyone with access to your API_ID, API_HASH, or BOT_TOKEN can take full control of your account. Use your hosting provider's dashboard to set these variables securely.

Ether uses environment variables for configuration. These can be set in a .env file for local deployment or in your cloud provider's dashboard.

Variable	Requirement	Description
API_ID	Required	Your Telegram API ID from my.telegram.org
API_HASH	Required	Your Telegram API Hash from my.telegram.org
OWNER_ID	Required	Your numeric Telegram User ID
BOT_TOKEN	Required	Your Bot Token from @BotFather
MONGO_URI	Required	MongoDB Atlas connection string
BOT_USERNAME	Optional	Auto-fetched from BOT_TOKEN; set manually only if needed
SESSION_NAME	Optional	MongoDB session document name (Default: etheruserbot)
DB_NAME	Optional	Database name (Default: Ether)
DEBUG	Optional	Set to true for verbose logging (Default: false)
WEB_SERVICE	Optional	Set to true when the host requires an HTTP health endpoint
PORT	Optional	Port for the web service (Default: 8080; Render uses 10000)

---

Deployment Options

Ether is a long-running Telegram client. For reliable operation, use a host that allows long-lived processes and provide a persistent MongoDB database for sessions and settings.

Render	Heroku	JustRunMyApp

Deployment Matrix

Target	Files Used	Runtime Type	How to Verify
Render	render.yaml, Dockerfile	Docker web service	HTTP health check at /health
Heroku	app.json, heroku.yml, Dockerfile	Container worker dyno	Worker logs and Telegram /login
Docker Compose / VPS	docker-compose.yml, Dockerfile	Local Docker service	docker compose config and /health
Manual Python	requirements.txt, main.py	Local Python process	Import and compile checks
JustRunMyApp / Generic Docker Host	Dockerfile	Long-running Docker container	Same env vars and health endpoint rules as Docker

Quick Start Guides

1. Cloud Hosting (Render - Recommended)

Render should be deployed as a Docker Web Service because Render requires web services to bind an HTTP port.

1. Fork this repository to your own GitHub account.
2. Click the Deploy to Render button above.
3. Connect your GitHub account and select the forked repository.
4. Use the checked-in render.yaml blueprint:
   • Runtime: docker
   • Dockerfile: ./Dockerfile
   • Health check path: /health
   • PORT=10000
   • WEB_SERVICE=true
5. Set the required environment variables from Configuration.
6. Deploy, then open:

   https://your-app.onrender.com/health
   

   Expected response:

   {"status":"healthy"}

7. Open your Telegram bot and run /login.

Important

Render Free web services sleep after idle periods and can restart at any time. The HTTP endpoint keeps the deploy valid, but it does not make the free plan always-on. Use a paid Render instance, VPS, or another always-on host for a 24/7 userbot.

---

Keep-Alive & Automation (Cloud)

Cloud providers often put free-tier apps to sleep after inactivity. External monitors can reduce idle sleep, but a paid always-on service or VPS is the more reliable option for a 24/7 userbot.

UptimeRobot (Keep-Alive)

To keep a Render web service receiving inbound HTTP traffic, set up a monitor to ping the health endpoint:

1. Go to UptimeRobot and create a free account.
2. Click Add New Monitor.
3. Monitor Type: HTTP(s)
4. Friendly Name: Ether Userbot
5. URL: https://your-app.onrender.com/health
6. Monitoring Interval: Every 5 minutes.
7. Click Create Monitor.

Cron-job.org (Scheduled Tasks)

If you need to trigger specific bot actions or ensure the web service remains active via external triggers:

1. Create an account at Cron-job.org.
2. Create a New Cronjob.
3. URL: https://your-app.onrender.com/health
4. Schedule: Every 5 or 10 minutes.
5. This acts as a secondary heart-beat for your bot.

---

2. Heroku Deployment

Heroku should be deployed as a container worker dyno. Do not run a web dyno unless you add a separate web process.

1. Click the Deploy to Heroku button above.
2. Enter a unique app name and fill in the required environment variables.
3. Once the build finishes, go to the Resources tab.
4. Confirm the worker dyno is enabled and the web dyno is disabled.
5. Set WEB_SERVICE=false for worker-only Heroku deployments.
6. Check logs:

   heroku logs --tail --ps worker -a your-app-name

7. Open your Telegram bot and run /login.

CLI deployment:

heroku create your-app-name
heroku stack:set container -a your-app-name
heroku config:set API_ID=... API_HASH=... OWNER_ID=... BOT_TOKEN=... MONGO_URI=... WEB_SERVICE=false -a your-app-name
git push heroku main
heroku ps:scale web=0 worker=1 -a your-app-name

Note

Heroku no longer has free dynos. Use a paid dyno type appropriate for a long-running worker.

---

3. JustRunMyApp (One-Click)

Use this path only if the platform supports long-running Docker containers and runtime environment variables.

1. Click the Deploy Now button for JustRunMyApp above.
2. Paste the repository URL: https://github.com/LearningBotsOfficial/Ether.
3. Choose Dockerfile-based deployment.
4. Set the required environment variables from Configuration.
5. If the platform requires an HTTP endpoint, set WEB_SERVICE=true and PORT to the platform-provided port.
6. Launch the app and wait for the status to show Running.
7. If a public URL is provided, verify /health.

4. Docker Deployment (Local / VPS)

The preferred method for developers and privacy-focused users.

# 1. Clone the repository
git clone https://github.com/LearningBotsOfficial/Ether.git && cd Ether

# 2. Create and configure your .env file
cp .env.example .env
nano .env

# 3. Build and launch with Docker Compose
docker compose up -d --build

# 4. Verify the service
docker compose ps
curl http://localhost:8080/health

For Windows PowerShell, the health check command is:

Invoke-RestMethod http://localhost:8080/health

Tip

Docker Compose sets WEB_SERVICE=true, exposes ${PORT:-8080}, and uses the /health endpoint for container health checks. If you set PORT in .env, use that value instead of 8080 in the health check URL.

5. Manual Setup (Linux / VPS / Windows)

For users who want full control over the environment.

1. Install Python 3.11+ Make sure you have Python 3.11 or higher installed on your system.

2. Prepare the Project Clone your repository and enter the directory:

   git clone https://github.com/LearningBotsOfficial/Ether
   cd Ether

3. Setup the Environment Create a virtual environment and install dependencies:

   python -m venv .venv
   
   # Activate the virtual environment
   # On Linux/macOS:
   source .venv/bin/activate
   # On Windows:
   .venv\Scripts\activate
   
   # Install dependencies
   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt

4. Configure Environment Variables Copy the example environment file and edit it with your credentials:

   cp .env.example .env
   nano .env  # Or your preferred editor

5. Run the Bot You can run the bot directly using:

   python main.py

   If your host requires a health endpoint, set:

   export WEB_SERVICE=true
   export PORT=8080

---

Managing Dependencies & Upgrading

Adding or Removing Packages

To add a new library:

python -m pip install <package-name>
# Then add the reviewed direct dependency pin to requirements.txt

To remove a library:

python -m pip uninstall <package-name>
# Then remove the direct dependency pin from requirements.txt

Syncing Pinned Dependencies

Install exactly the versions listed in requirements.txt:

python -m pip install -r requirements.txt

If you use uv:

uv pip install -r requirements.txt

Upgrading Dependency Pins

Pinned requirements do not upgrade automatically. To upgrade safely, check the latest package versions, edit requirements.txt, sync the environment, and run the verification commands in the deployment section.

---

Post-Deployment: Authentication

Unlike traditional userbots, Ether doesn't use risky "String Sessions". Follow these steps to authorize your account:

1. Open your bot on Telegram (the one created via @BotFather).
2. Send the /login command.
3. The bot will prompt you for your phone number.
4. Enter the OTP sent by Telegram (and your 2FA password if enabled).
5. Success! Your session is now securely stored in your own MongoDB database.

---

Command Reference

Ether provides a suite of professional tools. All userbot commands are prefixed with . by default.

Account & Session

Command	Action	Platform
/login	Starts the native Telegram OTP/2FA login flow.	Official Bot
/restart	Restarts the bot instance to apply changes.	Official Bot

System & Utility

Command	Description
.alive	View system status, uptime, and version info.
.ping	Check the current latency between Ether and Telegram.
.help	Open the interactive help menu (Inline Support).
.commands	Displays a full list of all loaded plugin commands.

Privacy & DM Shield

Command	Description
.allow	Approves a user to message you in DMs.
.disallow	Revokes a user's permission and enables the shield.
.setwelcome	Sets a custom welcome message for new DM users (Reply).
.clearwelcome	Resets the DM welcome message to default.
.setwarn <n>	Set max warnings before a user is auto-blocked.

Shortcuts & Management

Command	Description
.shortcut <name>	Save the replied message as a permanent shortcut.
.get <name>	Retrieve and send a saved shortcut.
.delshortcut <n>	Delete a specific shortcut by its name.
.shortcuts	List all your saved shortcuts and snips.
.tagall <msg>	Mention all members in a group safely.
.fonts <text>	Transform text into stylish mathematical fonts.

---

Plugin Development

Ether is built to be modular. You can add new features by creating a .py file in the plugins/ directory. Each plugin must implement a setup function.

The Setup Function

def setup(ether, db, owner_id):
    """
    ether: The Telethon TelegramClient instance.
    db: The PyMongo async database instance.
    owner_id: The numeric ID of the bot owner.
    """

Pro Plugin Example: notes.py

This example shows how to use the database to save and retrieve simple notes.

from telethon import events

def setup(ether, db, owner_id):
    # Collection reference
    notes = db["notes"]

    @ether.on(events.NewMessage(pattern=r"^\.save (\w+) (.+)$", outgoing=True))
    async def save_note(event):
        if event.sender_id != owner_id: return
        
        name = event.pattern_match.group(1)
        text = event.pattern_match.group(2)
        
        await notes.update_one(
            {"name": name}, 
            {"$set": {"content": text}}, 
            upsert=True
        )
        await event.edit(f"Note '{name}' saved successfully.")

    @ether.on(events.NewMessage(pattern=r"^\.getnote (\w+)$", outgoing=True))
    async def get_note(event):
        if event.sender_id != owner_id: return
        
        name = event.pattern_match.group(1)
        note = await notes.find_one({"name": name})
        
        if note:
            await event.edit(f"**Note {name}:**\n{note['content']}")
        else:
            await event.edit("Note not found.")

---

Community & Support

Get help, report bugs, and stay updated with the latest plugins and features from the Ether ecosystem.

Platform	Purpose	Link
Telegram Channel	Announcements, version releases, and security patches.	Join Channel
Telegram Group	Community support, plugin troubleshooting, and general chat.	Join Support
Developer Network	Collaboration with the LearningBotsOfficial ecosystem.	Join Network

Note

For technical bug reports and detailed feature requests, please use the GitHub Issues tracker.

---

Contributors

We appreciate the support and contributions from our amazing community.

---

Terms of Use & Licensing

Ether is a professional open-source framework. By utilizing this software, you agree to the following:

• Attribution: Original credits to LearningBotsOfficial must remain intact in all files.
• Forks: Public forks must link back to the original repository.
• Commercial Use: Reselling this project or distributing paid clones is strictly prohibited.
• Liability: Use this software responsibly. We are not responsible for any account bans or misuse.

© 2026 LearningBotsOfficial. All rights reserved. Licensed under the MIT License.

Made with love for the Open Source Community by LearningBotsOfficial

Back to Top