🌐 Bilingual out of the box — TeleBrief fully supports English and Persian (فارسی). Each user picks a language on first launch (or switches anytime with
/language), and the entire experience — menus, commands, digest cards, admin stats, and system messages — is rendered natively in that language, including right-to-left formatting and Persian numerals for Farsi.
"In a world drowning in information, the real art lies in what you choose to ignore."
TeleBrief monitors hundreds of Telegram channels covering technology, cybersecurity, the USD/gold market, crypto, and geopolitical conflict in real time. It strips out spam and low-value noise, then runs everything through a two-stage AI pipeline that returns scored, summarized reports with direct source links — delivered straight into a Telegram bot, fully localized in English and Persian.
The scraping core runs on deep Telethon (MTProto) access — no admin rights required, no aggressive rate limits, and always live. Every report is rendered as a clean, structured card right inside Telegram, and each user can shape their own feed with custom channels, time windows, categories, and their preferred language.
| ▶ Problem | Reality |
|---|---|
| Post volume | Thousands of posts a day across technical Telegram channels |
| Spam | ~70% is low-value or repetitive noise |
| Clickbait | ~20% is misleading headlines with no real substance |
| Actual signal | Only ~10% is worth reading — and that's exactly what TeleBrief surfaces |
|
|
|
|
| ▶ Feature | Description | Status |
|---|---|---|
| Two-layer AI analysis | Powered by DeepSeek V4 / OpenAI-compatible models with automatic fallback — extracts importance, reasoning, and technical impact | ✅ |
| Resilient model chain | Primary model → configurable text-model fallbacks → Gemini as a last resort, with retry limits at every hop — a report is never faked | ✅ |
| Live loading dashboard | Animated, stage-by-stage progress card while a report is generated, with an inline cancel button | ✅ |
| Background, cancellable reports | Report generation runs as a background task per user, so a "cancel report" tap is honored instantly instead of queuing behind it | ✅ |
| Flexible time filters | Preset windows from 6 to 720 hours, plus a fully custom hour range | ✅ |
| Per-user custom channels | Starts from a curated default list, then add or remove unlimited personal channels via /addchannel |
✅ |
| Smart pagination | 10 items per page, ranked by importance, with a "load more" button for the rest | ✅ |
| Mandatory-join gate | Optional membership check against a required channel before granting access, fail-safe by design | ✅ |
Admin analytics (/stats) |
Silent, admin-only command showing total users, daily growth, requests by category, and a paginated leaderboard | ✅ |
| USD & gold rates | Latest USD and 18k gold prices pulled from multiple currency channels, always resolved to the freshest real-world timestamp | ✅ |
| Crypto & geopolitical market report | A narrative overview of crypto market conditions and war/geopolitical risk, plus sourced highlights with 10-item pagination | ✅ |
| Atomic state persistence | User state (preferences, stats, channels) is written atomically to disk to survive concurrent writes and crashes | ✅ |
| Full English & Persian localization | Per-user language selection via /language, with natively rendered menus, commands, digest cards, and admin stats — right-to-left layout and Farsi numerals included |
✅ |
| Media support | Images, files, and voice messages | ⏳ |
| Full analytics dashboard | Usage metrics and performance monitoring UI | ⏳ |
graph TD
A[📡 Telegram Channels] --> B[⚙️ Harvesting — Telethon MTProto]
B --> C{Initial Spam Filter}
C -->|Passed| D[🧠 Stage 1 — Shortlisting]
C -->|Dropped| X[🗑️ Spam]
D --> E[🧠 Stage 2 — Merge & Scoring]
E --> F{Importance Score 0-100}
F --> G[🚀 Delivered to Telegram Bot]
G --> H[📑 Smart Pagination]
G --> I[⏱️ GitHub Actions Scheduler]
E -.model unavailable.-> J[♻️ Fallback Models → Gemini]
J --> F
| Metric | Value |
|---|---|
| Analysis time | 15–45 seconds |
| Scan throughput | ~100 messages/sec |
| Memory footprint | Under 150 MB |
| Pagination latency | Under 1 second |
Prerequisites: Python 3.11+ · a Telegram account · Telegram API ID/Hash from my.telegram.org · a bot token from @BotFather · an API key for the LLM gateway
git clone https://github.com/Amin-Moniry/TeleBrief.git
cd TeleBrief
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
pip install -r requirements.txt
python -c "
from telethon.sync import TelegramClient
from telethon.sessions import StringSession
API_ID = YOUR_API_ID
API_HASH = 'YOUR_API_HASH'
with TelegramClient(StringSession(), API_ID, API_HASH) as c:
print(c.session.save())
"
cp .env.example .env
# edit .env with your own values
python command_bot.py
|
|
|
docker run -d --name telebrief \
--env-file .env telebrief:latest |
| Layer | Technology |
|---|---|
| Language | Python 3.11+ |
| Telegram client | Telethon (MTProto) |
| Bot framework | python-telegram-bot |
| LLM gateway | xKiro (OpenAI-compatible) with Gemini fallback |
| Concurrency | asyncio with a bounded fetch semaphore |
| Persistence | JSON, written atomically |
| CI/CD | GitHub Actions |
| Component | Minimum | Recommended |
|---|---|---|
| OS | Windows 10, Ubuntu 20.04+, macOS 11+ | Latest stable versions |
| Python | 3.11 | 3.12+ |
| RAM | 512 MB | 1 GB+ |
| Network | Stable outbound connection | Low-latency, always-on |
| Hosting | Any Python 3.11+ host | Railway / Render / Fly.io / VPS with process manager |
TeleBrief/
├── .gitignore
├── assets/
│ └── Telebrief.jpg # Logo used at the top of this README
├── main.py # Process entry point — boots the bot
├── command_bot.py # Telegram handlers: commands, callbacks, menus, /stats
├── digest_core.py # Scraping, two-stage AI pipeline, formatting, scoring
├── localized_bot.py # Language state helpers + localize() dispatch
├── ui_en.py # English strings, menus, and card templates
├── ui_fa.py # Persian (فارسی) strings, menus, and card templates
├── bot_state.json # Atomic, on-disk user state (prefs, stats, channels)
├── requirements.txt # Python dependencies
├── runtime.txt # Pinned Python runtime for deployment platforms
├── Procfile # Process declaration for Railway / Heroku-style hosts
└── README.md
bot_state.json is written atomically on every update so concurrent requests and crashes never leave it corrupted — treat it as runtime data, not something to hand-edit.
API_ID=YOUR_ID
API_HASH=YOUR_HASH
SESSION_STRING=YOUR_SESSION
BOT_TOKEN=YOUR_TOKEN
XKIRO_API_KEY=YOUR_KEY
API_BASE_URL=https://api.xkiro.com/v1
DEFAULT_MODEL=deepseek/deepseek-v4-pro
FALLBACK_MODELS=mistralai/mistral-medium-3.5
GEMINI_API_KEY=YOUR_GEMINI_KEY
GEMINI_MODEL=gemini-2.5-flash
ADMIN_ID=YOUR_TELEGRAM_NUMERIC_ID
HOURS_WINDOW=24
CURRENCY_HOURS_WINDOW=6
BATCH_CHAR_LIMIT=12000
MODEL_RETRIES=3
ANALYSIS_CONCURRENCY=1
MAX_CONCURRENT_FETCHES=1DEFAULT_MODEL = "deepseek/deepseek-v4-pro" # primary reasoning model
FALLBACK_MODELS = "mistralai/mistral-medium-3.5" # comma-separated fallback chain
GEMINI_MODEL = "gemini-2.5-flash" # last-resort fallbackADMIN_ID is the only account with access to /stats; the command stays silent for everyone else so it doesn't reveal itself.
Bot doesn't start
ps aux | grep command_bot.py
kill -9 PID
# grab a fresh token from @BotFatherLLM gateway returns a 503
curl https://api.xkiro.com/v1/models
# switch models
DEFAULT_MODEL=deepseek/deepseek-v4-proSession expired
Re-run the SESSION_STRING script above
Rate limited
Lower ANALYSIS_CONCURRENCY / MAX_CONCURRENT_FETCHES, or raise BATCH_CHAR_LIMIT=20000
TeleBrief ships as a fully bilingual bot — Persian (فارسی) is the default, and English is one tap away.
- Language picker on first launch, and switchable anytime with
/language - Per-user, persisted preference — stored in each user's state and respected across every command, report, and admin view
- Native command menus — Telegram's command list itself changes language (e.g.
/addchannelvs its Persian label) immediately after a user switches - Right-to-left Persian layout with Farsi numerals (۰۱۲۳۴۵۶۷۸۹) throughout digest cards and stats
- Consistent card contract across both languages — the same title, importance score, expandable summary, expandable analysis/key-points block, recommended-actions block, direct-source bullets, and footer, just rendered natively left-to-right in English and right-to-left in Persian
- Language-leak guard — a final check rejects or re-renders model output if the wrong language slips into a report, so an English report never ends up with stray Persian prose (or vice versa)
| Question | Answer |
|---|---|
| How accurate is the analysis? | 80–90% on importance scoring, tuned on tech/security patterns |
| Can I use a self-hosted LLM? | Yes — any OpenAI-compatible API (Ollama, LocalAI, etc.) |
| What happens if the primary model fails? | It automatically retries, then falls through the configured fallback models, then Gemini — never a fabricated report |
| How's privacy handled? | Local analysis, no persistent logs, subject to your chosen API provider's ToS |
| Can I add my own channel? | Yes — use /addchannel and send @channel_name |
| Which languages are supported? | English and Persian (فارسی), fully — switch anytime with /language |
| Why is it slow sometimes? | Large batch size or a slow LLM response — try raising ANALYSIS_CONCURRENCY |
|
🧠 AI Channels @RoidBest · @Farda_Ai · @Lumosel · @asrnovin_ir · @perplexity · @cryptoquant_official · @hiaimediaen · @Hugging_face_news · @samiotech · @arzdigitalb · @Artificial_intelligence_in · @DeepLearning_ai · @HomeAI · @Artificial_Intelligence_AI · @data_science_info |
🛡️ Security Channels @cybersecurityexperts · @thehackernews · @cibsecurity · @Cyber_Security_Channel · @androidMalware · @cloudandcybersecurity · @itsecalert · @intsec · @topcybersecurity |
|
🪙 Crypto & War Channels @eco_ehsan · @Nobitexmag · @mihanblockchain · @helperhash · @whale_alert_io · @CoinDeskGlobal · @tokenbaz_com · @asiasarmayeh |
💵 USD & Gold Channels @irancurrency · @TetherLand · @navasanchannel |
Add unlimited personal channels straight from the bot menu
/start → boot up and show the main menu
/menu → quick category picker
/ai → latest AI digest
/security → latest cybersecurity digest
/crypto → crypto market & geopolitical risk report
/addchannel → add a personal channel to your feed
/price → live USD & 18k gold rates
/language → switch between English and Persian (فارسی)
/help → usage guide
/about → about TeleBrief
/stats → admin-only usage analytics
- Fork the repo
- Create a branch:
git checkout -b feature/your-idea - Commit:
git commit -m 'feat: description' - Push:
git push origin feature/your-idea - Open a Pull Request
Released under CC BY-NC-ND 4.0 — free to use and study for learning and non-commercial purposes; commercial use, taking the underlying idea/architecture for another product, or distributing modified versions is not permitted without written permission. Full details in LICENSE