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
`BOT_TOKEN`	Required	Your Bot Token from @BotFather
`OWNER_ID`	Required	Your numeric Telegram User ID
`MONGO_URI`	Required	MongoDB Atlas connection string
`BOT_USERNAME`	Required	Your Bot's username (without @)
`DB_NAME`	Optional	Database name (Default: `Ether`)
`DEBUG`	Optional	Set to `true` for verbose logging (Default: `false`)
`WEB_SERVICE`	Optional	Set to `true` for cloud keep-alive services
`PORT`	Optional	Port for the web service (Default: `8080`)

Deployment Options

Ether is designed to be deployed anywhere. Choose the platform that fits your needs.

Render	Heroku	JustRunMyApp

Quick Start Guides

1. Cloud Hosting (Render - Recommended)

Render provides the most stable environment for Ether with native Docker support.

Fork this repository to your own GitHub account.
Click the Deploy to Render button above.
Connect your GitHub account and select the forked repository.
Configure the Environment Variables (see Configuration).
- Crucial: Ensure WEB_SERVICE is set to true to prevent the service from sleeping.
Render will automatically build and deploy the container.

Keep-Alive & Automation (Cloud)

Cloud providers like Render often put free-tier apps to "sleep" after inactivity. Use these tools to ensure Ether stays online 24/7.

UptimeRobot (Keep-Alive)

To prevent Render from sleeping, set up a monitor to ping your bot's URL:

Go to UptimeRobot and create a free account.
Click Add New Monitor.
Monitor Type: HTTP(s)
Friendly Name: Ether Userbot
URL: Your Render app URL (e.g., https://your-app.onrender.com/)
Monitoring Interval: Every 5 minutes.
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:

Create an account at Cron-job.org.
Create a New Cronjob.
URL: Your Render app URL.
Schedule: Every 5 or 10 minutes.
This acts as a secondary heart-beat for your bot.

2. Heroku Deployment

Ideal for users familiar with the Heroku ecosystem.

Click the Deploy to Heroku button above.
Enter a unique app name and fill in the required environment variables.
Once the build finishes, go to the Resources tab.
Important: Turn off the web dyno and turn ON the worker dyno.
Render will automatically build and deploy the container.

3. JustRunMyApp (One-Click)

A simple, zero-config deployment platform.

Click the Deploy Now button for JustRunMyApp above.
Paste the repository URL: https://github.com/LearningBotsOfficial/Ether
Follow the on-screen prompts to set your Environment Variables.
Launch the app and wait for the status to show "Running".

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

Tip

Using Docker Compose handles the health checks and automatic restarts for you.

5. Manual Setup (Linux / VPS / Windows)

For users who want full control over the environment.

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

Prepare the Project Clone your repository and enter the directory:

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

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
pip install -r requirements.txt

Configure Environment Variables Copy the example environment file and edit it with your credentials:
```
cp .env.example .env
nano .env  # Or your preferred editor
```
Run the Bot You can run the bot directly using:
```
python main.py
```

Managing Dependencies & Upgrading

Adding or Removing Packages

To add a new library:

pip install <package-name>
# Then update requirements.txt
pip freeze > requirements.txt

To remove a library:

pip uninstall <package-name>
# Then update requirements.txt
pip freeze > requirements.txt

Upgrading All Packages

To upgrade all dependencies to their latest versions:

pip install --upgrade -r requirements.txt
pip freeze > requirements.txt

Syncing Environment

Whenever you pull new changes from GitHub that include an updated requirements.txt, simply run:

pip install -r requirements.txt

This ensures your local .venv matches the project's requirements.

Post-Deployment: Authentication

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

Open your bot on Telegram (the one created via @BotFather).
Send the /login command.
The bot will prompt you for your phone number.
Enter the OTP sent by Telegram (and your 2FA password if enabled).
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.

Made with love for the Open Source Community by LearningBotsOfficial

Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
assets		assets
config		config
core		core
logs		logs
plugins		plugins
services		services
storage		storage
utils		utils
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
.slugignore		.slugignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Procfile		Procfile
README.md		README.md
app.json		app.json
docker-compose.yml		docker-compose.yml
heroku.yml		heroku.yml
main.py		main.py
render.yaml		render.yaml
requirements.txt		requirements.txt
web_service.py		web_service.py

Folders and files

Latest commit

History

Repository files navigation

Ether Userbot System

Repository Statistics

Sovereignty & Security

Key Features

Repository Structure

Tech Stack & Dependencies

Configuration

Deployment Options

Quick Start Guides

1. Cloud Hosting (Render - Recommended)

Keep-Alive & Automation (Cloud)

UptimeRobot (Keep-Alive)

Cron-job.org (Scheduled Tasks)

2. Heroku Deployment

3. JustRunMyApp (One-Click)

4. Docker Deployment (Local / VPS)

5. Manual Setup (Linux / VPS / Windows)

Managing Dependencies & Upgrading

Adding or Removing Packages

Upgrading All Packages

Syncing Environment

Post-Deployment: Authentication

Command Reference

Account & Session

System & Utility

Privacy & DM Shield

Shortcuts & Management

Plugin Development

The Setup Function

Pro Plugin Example: notes.py

Community & Support

Contributors

Terms of Use & Licensing

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

Pro Plugin Example: `notes.py`