A modular Telegram UserBot built on telethon. integrates Gemini for context-aware automation, Edge-TTS for localized voice synthesis, and a custom media stack.

Installation · System Core · Modules Manual · Troubleshooting

Project Akasha is a userbot that actually understands context. instead of static replies, it reads the last few messages and writes something that fits — mimicking your tone and style.

it also includes a TTS wrapper for Amharic/English voice notes, a two-stage music downloader that goes easy on RAM, and a set of group management tools. runs on local machines or cloud (Heroku/Railway).

make sure your directory matches this layout. the bot uses relative paths for fonts and database files.

.
├── Dockerfile
├── LICENSE
├── README.md
├── README_AM.md
├── config.py
├── core
│   ├── database.py
│   └── utils.py
├── docker-compose.yml
├── gitignore
├── hero
│   ├── akasha_hero.png
│   └── image.png
├── install.sh
├── main.py
├── plugins
│   ├── admin_tools.py
│   ├── ai.py
│   ├── creative.py
│   ├── growth.py
│   ├── master_voice.py
│   ├── music.py
│   ├── security.py
│   ├── system.py
│   ├── whois.py
│   └── whois_support
│       └── shadow_tracker.py
├── procfile
├── release_backup
│   └── userbot-1.0.0.zip
└── requirements.txt

⚠ critical warning: project akasha contains heavy scraping and growth modules and other (.shadow, .addmembers). misuse will result in an instant and permanent telegram ban. before running this bot, you must read the anti-ban protocols.

requires Python 3.9+ and FFmpeg.

Ubuntu/Debian:

sudo apt update && sudo apt install python3 python3-pip ffmpeg -y

Windows:

1. install Python from python.org.
2. install FFmpeg and add it to system PATH.

pip install -r requirements.txt

create a .env file in the root directory.

# telegram
API_ID=123456
API_HASH=your_api_hash
SESSION=1BVts...

# gemini keys — separate with commas
GEMINI_KEYS=AIzaSy1...,AIzaSy2...,AIzaSy3...

# or individually
GEMINI_KEY1=AIzaSyD...
GEMINI_KEY2=AIzaSyF...
GEMINI_API_KEY=AIzaSy...

# database — leave empty for local json
MONGO_URL=

⚠︎ never commit your .env or session string to any public repo.

python main.py

validates keys on startup via Config.check_integrity().

for Render, Railway, or Heroku — skip the .env and inject these directly into the dashboard:

• API_ID
• API_HASH
• SESSION
• GEMINI_KEYS (comma separated: Key1,Key2,Key3)

managed by plugins/system.py. handles the away-state logic.

changes the tone of replies.

• sleep - short, groggy responses.
• work - professional, concise.
• gaming - dismissive/short.
• default - standard conversational style.

keeps replies from looking automated:

1. read delay: random 1-3s pause before marking as read.
2. typing: calculates len(response) * 0.1s to match realistic typing speed.

• Whois: .whois @user. pulls a user profile card (ID, DC, scam status, bio).
• Translator: Text //lang_code. replaces the message with the translation (e.g., Hey //am → ሰላም).
• Moderation:
  • .purge — deletes messages recursively.
  • .ban / .mute — standard user restrictions.
  • .zombies — scans for deleted accounts and removes them to fix member counts.

wrapper for Microsoft Edge TTS. supports SSML tags for pitch and rate control.

Command: .say [text] [flags]

• auto-switches between Mekdes (Amharic) and Jenny (English) based on script.

.whisper — shortcut for .slow + low volume.

pillow based image manipulation.

• Meme Gen: .meme [Top];[Bottom].
  • auto-fetches NotoSansEthiopic-Bold or NotoSansArabic based on script. caches fonts locally.
• Sticker Kang: .kang. converts media to 512px WebP and appends to your sticker pack.
  • skips files >5MB to avoid memory issues on VPS.

uses yt-dlp for SoundCloud/YouTube extraction.

1. .song [Query] — fetches metadata only. caches in RAM.
2. reply 1 to 5 to select.
3. downloads → converts to MP3 192kbps → writes id3 tags → uploads.

• .ai [prompt] — uses the rotated key pool.
• reply to an image with .ai explain — downloads to memory buffer, sends to vision API.
• .img / .imgs — pulls images from DuckDuckGo.

disabled by default. hooks into MessageMedia events - if ttl_period > 0:

1. downloads media to temp.
2. forwards to Saved Messages.
3. tags with "ꗃ vault capture".

• .hack @user — edits a message repeatedly to simulate a terminal sequence. prank only.

session-based tool for moving users between groups. handles dedup, filtering, and rate limits automatically.

• Collect: .scrape @group - pulls users into local session.
  • multi-source: .scrape @g1 @g2 @g3 - merges and dedupes across all.
  • ranks by last-seen activity (online > recently > last_week > last_month).
• Move: .addmembers @dest - processes the list into a destination group.
  • skips anyone already there. most-active users go first.
  • adaptive sleep - shortens on clean runs, extends after rate limit hits. jitter on every pause.
• Status: .gstatus - live progress bar, eta, and per-result breakdown.
• Stop: .gstop - graceful cancel. session stays intact.
• Filters: .gfilter - set before collecting.
  • max_last_seen - activity cutoff (online | recently | last_week | last_month | any).
  • require_username, require_phone, exclude_premium, max_count.
  • example: .gfilter max_last_seen=recently require_username=true max_count=1000
• Data: .gexport / .gimport - save and restore session as json.
• Clear: .gclear - resets session. filters and rejected cache are kept.

note: invites go out from your account. telegram restricts accounts that move too fast. use a secondary account you don't mind losing - not your main.

deep profiling tool to monitor target activity across mutual groups. handles async scraping, rate limit bypassing, and cross chat aggregation without triggering api bans.

• features:

  • timezone & sleep window estimation
  • sentiment, language & typing habits (caps, lazy punctuation, emoji frequency)
  • reply speed analayzer & chat thread depth tracking
  • securely routes generated dumps to saved messages

• commands:

  • .shadow @username - dump profile data via username
  • .shadow <id> - dump profile data via user id
  • .shadow (in reply) - dump profile of the replied user

FFmpeg not found: make sure FFmpeg is in your system PATH or install via apt.

API key errors: keys auto-rotate, but if all are exhausted .ai will return an error. check your key quota.

Dependency issues:

pip install --force-reinstall -r requirements.txt

Licensed under the MIT License.

Project Akasha v1.0
Built for the Unknown purpose ☕︎.