TeleAutomator — AI Telegram Chat Automation & Mini App

The open, modern AI-powered Telegram userbot and personal automation assistant.
Context-aware auto-replies with Google Gemini & OpenAI LLMs, Telethon MTProto user account client, and an Android Material 3 Expressive claymorphic Mini App control panel.

🔑 First Time Setup & Requirements Guide
Wondering which API keys, Telegram IDs, and environment settings are required? Read REQUIREMENTS.md for a beginner-friendly walkthrough on where to get your TG_API_ID, TG_API_HASH, bot token, and free AI key.

🚀 Deploying to Railway, Render, or Cloud VPS 24/7?
For complete step-by-step cloud deployment walkthroughs, automated build guides, and environment variable configurations, see DEPLOYMENT.md.

⚡ Quickstart (Local)

📖 Before starting, configure your credentials in .env. See REQUIREMENTS.md for where to find each value.

# 1. Clone repository
git clone https://github.com/mkr-infinity/TeleAutomator.git && cd TeleAutomator

# 2. Universal automated setup (installs dependencies and creates .env)
./setup.sh

# 3. Authenticate with your Telegram account (Phone, OTP, 2FA)
./authenticate.sh

# 4. (Optional) Export your headless Cloud session string:
./session.sh

# 5. Start TeleAutomator
./start.sh

(Windows / cross-platform: python run.py --setup -> python run.py --auth -> python run.py --session -> python run.py)

📱 Telegram Mini App (Web App GUI)

TeleAutomator includes a built-in Telegram Mini App running concurrently on the same server/container without requiring a separate domain or infrastructure.

• Direct Launch in Telegram: Registered automatically as the bot's persistent chat menu button (Open) via Telegram's setChatMenuButton API, and accessible via /miniapp inline Web App buttons.
• Sleek Loading Screen: Smooth animated startup with glowing project logo, gradient progress bar, and instant state hydration.
• Overview Dashboard: Live status pill, 24h reply counters, speaking style, quiet hours schedule, and quick controls (Pause 30m, Resume, Emergency Stop, Mode switch).
• Chats & Memory Management: Capsule-style chat cards showing profile initials, titles, allowlist status, per-chat custom personas, voice profiles, and isolated disk context files (data/contexts/{chat_id}.json).
• AI Engine & Testing Playground: Custom base URL configuration, live model fetch from /models endpoints, multi-model selection with automatic fallback rotation, and an interactive test playground.
• Draft Approvals: Approve or reject drafts with in-place card updates (zero message deletions on Telegram).
• Action History & Diagnostics: More → Action history shows sent, skipped, blocked, and failed actions with filters and live engine details. It keeps at most 1,100 metadata entries, excluding message bodies and command arguments.
• Reply Feedback & Stages: Rate automated messages from Overview → Recent replies as helpful, unneeded, off-topic, or a style mismatch. More → Reply feedback & stages shows the ratings, filters, and context/writer/local-check stages. Ratings guide only their own chat, and rejected replies are checked before sending again.
• Preference Export & Import: The main owner can download a JSON backup and preview a merge before applying it. Reply settings, keyword rules, and separate chat profiles are included; credentials, access permissions, and conversation history are excluded. Keep exported prompts and notes private.
• Access Control & Paywall: Multi-user permissions with an automated authorization note (100 Stars or 1 TON to @mkr_infinity).

📑 Operating Modes

Switch modes on the fly from terminal, the Mini App GUI, or your Telegram Control Bot:

📱 Remote Control & Command Reference

Manage your automation straight from your phone by texting your Control Bot:

Permanent Group Context & Memory

Core Controls & Identity

AI Models, Quota & Cooldowns

Custom chat cooldowns override the default range; resetting a chat restores the default. Each outgoing bubble follows the current cooldown and safety controls. Removed chats and revoked users stay removed after a restart, including entries originally configured in the environment.

Only allowed chats are processed or cached. /clearcontext clears that chat's rolling history and recap while keeping its permanent notes, pins, persona, and voice profile. In-flight summaries and history fetches cannot restore cleared memory. The Mini App enforces the same command grants as the control bot.

Group participation samples relevant conversations using the per-chat rate or global default (15% unless configured). Other people's reply threads and routine closers are ignored. Group messages post without quoted replies. The master prompt permits NONE for intentional silence; custom personas inherit the same rules. Outgoing checks block @tags, links, and known participant names, including keyword replies and approvals. Unfamiliar names still rely on the prompt. Identity and automation questions stay silent for the account owner to answer.

Reply preparation has three stages. A background context worker observes safe messages from allowed chats even in mention-only mode, coalesces updates to data/contexts/{chat_id}.json, and batches model recaps after new messages. Automatic recap attempts are at least 60 seconds apart per chat, with at most two recap jobs running together. The writer uses current messages, that chat’s notes/persona/voice, and recent owner feedback. A local final stage enforces text rules without another model call; stale unsolicited group drafts and drafts made before a memory reset are discarded. Feedback also applies to approved and keyword replies at delivery. Up to 500 ratings are retained, separately from the rolling message cache; clearing chat memory clears its ratings too. Model relevance still requires real-chat review.

🧪 Testing & Verification

Run the automated test suite locally:

./test.sh
# Or via universal runner:
python run.py --test

Tests cover configuration, authorization, safety guards, quiet hours, live custom cooldowns, isolated chat memory, duplicate approvals, and mocked Telegram/AI workflows. Install Node.js to include the Mini App JavaScript workflow checks; pytest skips that check when Node.js is unavailable. No live Telegram account or AI API key is needed.

With Playwright and Chromium installed, pytest also checks the real Mini App in a mobile browser: popup scrolling, small swipes, fullscreen compatibility, keyboard resizing, failed saves, repeated taps, preserved drafts, and reconnects across six window sizes. These checks use local fixtures. PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH can select an existing Chromium binary.

The Mini App requests fullscreen on supported Telegram clients, respects Telegram/system safe areas, and disables body swipes that would minimize it. Telegram still controls its native header gestures. Settings use expandable sections; popups keep failed edits visible and require confirmation before discarding unsaved input. Public assets are cached separately from authenticated API responses.

Automated outgoing messages start with a capital letter, including each separate bubble and approved draft. Remaining casing, such as API and iPhone, is preserved.

☕ Support & Donations

If TeleAutomator saves you time or empowers your personal workflow, consider supporting development:

• ☕ Buy Me a Coffee: https://buymeacoffee.com/mkr_infinity
• 🇮🇳 UPI (India): mkr-infinity@ybl

📄 License & Attribution

Licensed under the Proprietary Source-Available License. Free for personal use.
Author: Mohammad Kaif Raja (@mkr-infinity)

🔍 Topics & Keywords

telegram · telegram-bot · telegram-automation · telegram-userbot · telegram-miniapp · telethon · ai · ai-agent · llm · gemini · chatgpt · chatbot · auto-reply · automation · selfbot · python · material-design · claymorphism · tma · assistant