Smart Broadcasting System

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• bot.py
• requirements.txt
• .env.example (referenced via documentation in README)
• Dockerfile (referenced via documentation in README)

The Smart Broadcasting System manages high-volume message delivery to Telegram channels and direct messages to users. It operates as part of a larger Telegram management suite that includes AI-powered summarization and moderation tools.

The system targets specific audience segments and supports various media types, including photos, videos, and documents. It utilizes both a standard Bot mode and a high-throughput Business mode via the Telegram Business API.

Sources: README.md:124-128, README.md:162-166

Broadcasting Architecture

The broadcasting logic differentiates between channel-wide announcements and direct-to-user campaigns. The system provides multiple delivery modes to handle rate limits and organizational needs.

Delivery Modes

The system implements two primary delivery methods for broadcasting:

• Bot Mode: Delivers messages at a rate of 20 messages per second.
• Business Mode: Utilizes the Telegram Business API for enterprise-level communication.

Sources: README.md:164-166

Audience Segmentation

The system filters recipients into seven distinct audience segments to ensure targeted broadcasting.

Segment	Description
All	Every registered user in the database.
VIP	Users marked with high-priority status.
Premium	Users with active premium subscriptions.
Active	Users who have interacted with the bot recently.
New	Recently joined users.
By Channel	Users associated with specific Telegram channels.

Sources: README.md:125-126

Message Processing Flow

When a broadcast is initiated, the system processes the request through a pipeline that handles media attachments and delivery logic.

The diagram shows the workflow from audience selection to final delivery execution.
Sources: README.md:124-128, README.md:166

Implementation Details

The underlying bot infrastructure uses urllib3 for network requests and handles communication with the Telegram Bot API via a centralized request function.

Request Handling

The bot executes API calls using a PoolManager and processes JSON payloads.

def telegram_api(method: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
    response = http.request(
        "POST",
        f"https://api.telegram.org/bot{BOT_TOKEN}/{method}",
        body=json.dumps(payload or {}).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        timeout=urllib3.Timeout(connect=10.0, read=POLL_TIMEOUT + 10.0),
    )
    data = json.loads(response.data.decode("utf-8"))
    return data

Sources: bot.py:40-53

Feature Summary

The broadcasting system integrates with several auxiliary modules to enhance message delivery.

• Media Support: Full support for photos, videos, documents, and polls.
• Dynamic Placeholders: Messages use tags like {name}, {username}, and {channel} for personalization.
• Campaign Management: Supports bulk and drip campaign modes for scheduled delivery.

Sources: README.md:127-128, README.md:144-146, README.md:163-165

Configuration

The system behavior is controlled via environment variables that define timeouts and message retention policies.

Variable	Default	Purpose
TELEGRAM_BOT_TOKEN	None	Authentication for the Telegram API.
POLL_TIMEOUT	30	Long-poll duration in seconds.
MAX_STORED_MESSAGES	100	Message history limit for chat-based context.

Sources: bot.py:22-25, README.md:46-52

The Smart Broadcasting System serves as a core component for Telegram channel and group management, providing scalable communication tools for businesses and agencies.