echosonar 0.1.4

Telegram Monitoring User Bot

🛰️ EchoSonar

Enterprise-grade Telegram monitoring user bot built with Telethon. It acts as an automated bridge, monitoring your private or public channels for specific keywords and instantly copying and re-uploading content to a destination of your choice.

🛠️ Prerequisites

• Python >= 3.10
• Telegram account with active App credentials (api_id, api_hash) from my.telegram.org.
• An execution environment (Local Machine or Linux VPS).

---

✨ Key Features

• 🛡️ Content Protection Bypass: Automatically downloads and re-uploads media from restricted channels where "Saving Content" is disabled.
• 📂 Full Album Support: Intelligently gathers media groups (albums) and forwards them as a single cohesive unit.
• 👤 Human-Like Behavior: Implements randomized delays (3-8s) and manual re-upload flows to mimic human activity and reduce account flagging risks.
• 🔄 Hot-Reloading: Update keywords, monitored channels, or destinations via CLI without restarting the running bot.
• 🕵️ Private Channel Support: Easily monitor private channels using internal numeric IDs.

---

🚀 Installation & Usage

Echosonar is designed to be installed in an isolated environment, choose the installation method that fits your environment best:

Option 1: Docker (Recommended for Servers & Continuous Running)

Run the bot as an isolated background service:

docker compose up -d

👉 Follow our dedicated Docker Deployment & Management Guide to set up your runtime container and configure hot-reloading keys.

Option 2: UV / Pipx (Recommended for Local CLI Management)

You can execute the application instantly from PyPI without downloading the source code, or install it permanently into its own isolated environment on your device:

• Execute instantly with UV:

  uvx echosonar run
  

• Install permanently with Pipx:

  pipx install echosonar
  

---

🛠️ Quick Start

1. Configuration

Run the setup command to input your Telegram API credentials (get them at my.telegram.org):

echosonar setup

2. Find Private IDs

If you need to monitor private channels, use the following command to see all your joined chats and their internal IDs:

echosonar list-ids

3. Add Monitoring Targets

# Add a public channel by username
echosonar channels add "@PublicChannel"

# Add a private channel by numeric ID (use -- to handle negative numbers)
echosonar channels add -- "-1001234567890"

# Add keywords
echosonar keywords add "urgent"

4. Run & Authenticate

Start the bot once in your terminal to complete the one-time Telegram login:

echosonar run

---

🏠 Running Live 24/7

On a Server (Linux/VPS)

The professional way to run EchoSonar on a server is using systemd. This ensures the bot starts on boot and restarts automatically if it crashes.

1. Create the service file: sudo nano /etc/systemd/system/echosonar.service

2. Paste configuration: (Replace youruser with your Linux username)

   [Unit]
   Description=EchoSonar Telegram Bot
   After=network.target
   
   [Service]
   User=youruser
   ExecStart=/home/youruser/.local/bin/echosonar run
   Restart=always
   RestartSec=10
   WorkingDirectory=/home/youruser
   
   [Install]
   WantedBy=multi-user.target
   

3. Start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable --now echosonar
   

On a Personal Computer

For local background execution, use a terminal multiplexer like Screen or TMUX:

# Create a new session
screen -S echosonar

# Run the bot
echosonar run

# Detach (Press Ctrl+A then D)
# The bot will continue running in the background.

---

📖 Detailed Documentation

For a full list of all available commands and advanced usage, see COMMANDS.md.

⚖️ Disclaimer

This tool is for personal automation and research purposes. Please respect Telegram's Terms of Service and the copyright of content creators. Use of user bots carries a risk of account restriction if used for spam or malicious activity.