This project is a next-generation conversational marketing self-bot for Telegram designed to replace aggressive, blind group spamming with intent-driven AI recommendations.
Traditional Telegram marketing bots ('Tabchi') blindly blast identical promotional banners into hundreds of random groups, alienating users, triggering instant spam reports, and quickly burning through phone numbers.
In stark contrast, this smart system operates entirely on genuine user intent. It monitors group discussions and leverages an AI Decision Engine to evaluate whether a user is actively looking for a product or solution. Only when a clear need is verified with high confidence (>75%) does it craft a natural, courteous, and context-aware conversational response. To the recipient, it feels like an authentic recommendation from a fellow community member rather than a bot.
The Problem
Conventional mass-marketing bots on Telegram suffer from severe structural failures:
1. Blind & Irrelevant Spamming: Sending generic promotions to groups where no one has interest or intent, yielding near-zero conversion and maximum irritation.
2. Rapid Account Blacklisting & Bans: Annoyed users flag repetitive spam, causing Telegram's anti-abuse algorithms to permanently ban numbers within hours.
3. Rigid, Unnatural Phrasing: Legacy bots cannot understand nuance, answering context with static ad templates that scream automation.
4. Duplicate Harassment: Without centralized persistence, bots repeatedly message the same users, generating backlash from group admins.
The Solution
The Smart AI Campaign Engine fundamentally redesigns conversational outreach:
• Intent-Targeted Detection (No Blind Spam): Continuously analyzes conversations to discover users expressing specific questions or pain points solvable by the promoted product.
• AI Decision Engine & Confidence Scoring: Candidate messages are evaluated against the campaign profile. Only messages reaching strict confidence thresholds (>=0.75) are approved for replies.
• Natural & Personalized Tone: Replies match the conversation's mood (friendly, formal, or neutral) with concise, helpful prose rather than aggressive sales pitches.
• Cosine Similarity Guard: Replies are vectorized and compared against previously sent texts to guarantee lexical diversity and prevent repetitive patterns.
• Anti-Duplicate Safeguard: Tracks contacted users across campaigns to strictly prohibit double-messaging.
• Batch Review Workflow: Allows human operators to review and approve AI-generated replies directly via an admin Telegram bot before dispatch.
• Multi-Account ClientPool: Rotates through authenticated real user sessions with human-like delays (5–30s) to completely avoid rate limits and account suspensions.
System Flow & Architecture
Architected with asynchronous Python (asyncio) and Clean Architecture principles:
- Campaign Engine: Orchestrates keyword generation, message scraping, and scheduled execution intervals via APScheduler.
- Multi-LLM Provider Chain: Hierarchical fallback (OpenAI → Gemini → Anthropic) equipped with circuit breakers for high availability.
- Anti-Duplicate & Vector Similarity Layer: Enforces cosine distance checks and persistent recipient deduplication.
- Telegram MTProto Infrastructure: High-speed session handling powered by Telethon across distributed client instances.
01
🔍
Targeted Search
Scans Telegram groups for active questions & keywords related to the product.
02
🧠
AI Need Verification
AI evaluates if user genuinely needs the product. Rejects message if confidence < 75%.
03
💬
Conversational Natural Reply
Generates friendly, human-like contextual advice rather than a rigid advertising banner.
04
🛡️
Anti-Duplicate & Diversity
Vector similarity checks ensure diverse phrasing while duplicate guards prevent re-messaging.
05
🚀
Safe Session Dispatch
Distributed ClientPool sends message with randomized delays to keep accounts 100% safe.
Technical Challenges & Solutions
Eliminating Blind Spamming via AI Intent Scoring
Challenge
Generic bots spam irrelevant threads, wasting API quotas and damaging brand reputation through community backlash.
Solution
Engineered a two-phase AI evaluation pipeline that analyzes semantic intent against product features, ignoring any candidate below the 0.75 confidence threshold.
Impact: 100% elimination of blind spam with conversations turning into genuine inbound inquiries.
Dynamic Variation & Cosine Similarity Detection
Challenge
Sending syntactically similar replies across multiple groups triggers Telegram's heuristic spam filters and reveals automation.
Solution
Integrated Scikit-learn TF-IDF vectorization and cosine similarity checks to ensure no two replies in a cycle exceed 0.85 similarity.
Impact: Completely unique, natural-sounding replies that read like genuine personal advice.
Multi-Account Session Rotation & Anti-Ban Architecture
Challenge
High-frequency messaging triggers FloodWait exceptions and account bans from Telegram's MTProto security servers.
Solution
Designed a Round-Robin ClientPool with randomized delays (5–30s) and cycle quotas, isolating sessions from platform restrictions.
Impact: 24/7 continuous operation with zero session revocations.
Results & Metrics
• Complete elimination of blind spam through strict AI intent verification.
• Significantly higher conversion and reply rates compared to static advertising copy.
• Zero account suspensions achieved through intelligent session pooling and randomized rate pacing.
• Automatic failover across 3 tier-1 AI providers (OpenAI, Gemini, Anthropic) ensuring 99.9% uptime.
• Optional batch review workflow for human-in-the-loop campaign oversight.
