tg-bot/README.MD

Streaming Overseer: A Telegram Monitoring Tool

This tool monitors specified Telegram channels for messages that contain certain keywords and forwards them to a private channel. It's built using Python and Telethon, a Telegram client library.

Features

• Monitors multiple channels.
• Searches for messages with specified keywords.
• Forwards matching messages to a private channel.

Prerequisites

Before you can use this tool, you need to set up a few things:

1. Python 3.8+ (Tested on 3.10+)
2. Telethon Library
3. A Telegram API key and API Hash
4. A Telegram Bot
5. A Private Telegram Channel

Installing Python

Download and install Python from python.org.

Setup Instructions

Obtaining Telegram API ID and Hash

1. Login to your Telegram account at Telegram Core.
2. Go to API development tools and fill out the form.
3. You will get an api_id and api_hash which are needed for the tool.

Creating a Telegram Bot

1. Open Telegram and search for BotFather.
2. Send /newbot and follow the instructions to create your bot.
3. Copy the token provided by BotFather.

Setting Up a Private Channel

1. Create a new channel in Telegram.
2. Switch the channel's privacy to private in the channel settings.
3. Add your bot as an administrator to the channel.

Configuration Files

The script uses several files for configuration:

• credentials.json: Automatically created if not present. It stores API keys, bot token, and private channel ID.

• keywords.txt: Contains keywords to monitor. Supports special modifiers for dynamic matching:

  • * at the end allows up to three additional characters.
  • ** allows up to six additional characters.
  • # at the start includes numeric characters (up to three).
  • ## includes numeric characters (up to six).

  Note: Separate keywords using commas. Keywords can span multiple lines for readability; newlines are ignored.

• channels.txt: List of channel usernames (the part after t.me/) to monitor

• Separate channel names with commas, and feel free to list them across multiple lines for better readability. Newlines between names are ignored.

  Note: Ensure you have joined any channel you wish to monitor.

Examples

• keywords.txt

  hello*, world**, #123,
  ##123456, #or_any_combination**
  

• channels.txt

  python, daily_news,
  target3, target4
  

Running the CLI Tool

python streaming_overseer.py

Web Control Panel (FastAPI + Vue)

The project now ships with a FastAPI backend (backend/) and a Vue 3 dashboard (frontend/) so you can update credentials, manage keywords/channels, and watch matches in real time.

Authentication

• All API routes (except /api/auth/token) are protected with JWT. The default credentials are admin / admin123 and are stored in users.json.
• After the first login, use the UI “change password” endpoint (or call POST /api/auth/change-password) to update the password. The JWT expires after 60 minutes.
• Include the bearer token in the Authorization header for REST calls; the frontend handles this automatically after you log in from the new login page.

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r ../requirements.txt
uvicorn app.main:app --reload

The API is exposed on http://localhost:8000/api. Important endpoints:

• POST /api/auth/token, GET /api/auth/me, POST /api/auth/change-password
• GET /api/credentials (list), POST /api/credentials (create), PUT /api/credentials/{id} (update), DELETE /api/credentials/{id}, POST /api/credentials/{id}/activate, GET /api/credentials/active
• GET/PUT /api/keywords
• GET/PUT /api/channels
• POST /api/scanner/start|stop, GET /api/scanner/status
• GET /api/matches, GET /api/matches/stream

Frontend

cd frontend
npm install
npm run dev

Set VITE_API_BASE in a .env file if your backend is not running on http://localhost:8000/api. Once the dev server starts, visit http://localhost:5173/login, log in with the admin user, and the dashboard will become available.

Production Notes

• FastAPI already enables permissive CORS for local development; tighten it for production.
• Ensure credentials.json, keywords.txt, channels.txt, and users.json are stored securely; the API reads/writes the same files as the CLI script.
• The Telethon scanner still forwards matching messages to the configured Telegram channel while also streaming match metadata to the dashboard.

Managing multiple credentials

• The “凭据配置”页面 now supports multiple Telegram API credentials. Each record stores API ID/API Hash/手机号/Bot Token/频道 ID，列表中可一键设为当前使用的账号。
• 新建或编辑凭据后，点击“设为当前”即可让扫描器切换到该账号运行；激活状态会同步到 credentials.json 中的 active 字段。