Telegram Notifications

What this solution does

The Telegram Notify module by Kommutator.net sends site event notifications to the Telegram messenger. For proper operation, the hosting environment must have access to Telegram servers.

The system monitors and notifies about new and paid orders, status changes, user registrations, content publishing, web form submissions, and other system events. Configuration is performed via the administrative interface without requiring programming.

Addressing and Events

Includes a ready catalog of events for online stores, users, information blocks, web forms, and system processes. Separate recipients can be configured for each event category and for each site in a multi-site configuration. User-defined recipient lists can be created and applied to multiple categories simultaneously. Filters are available for information blocks and web forms to send notifications only for specific entities. If necessary, streams can be separated by assigning a distinct bot to each event category.

Delivery Mechanism

Utilizes a database queue with a priority system to ensure orders are processed before standard notifications. The system implements retry attempts with exponential backoff and jitter. An optional circuit breaker mechanism is available to protect against overload.

The Telegram notification module ensures reliable message delivery while respecting platform constraints. Send frequency is limited at both the bot and chat levels, applying to both web processes and CLI. Long messages are automatically split to comply with the 4096-character limit. Before sending, the system validates HTML and Markdown markup; if errors are detected, the content falls back to plain text. Inline buttons are available in the admin interface to link directly to relevant entities.

Recipient Management

A registry of known chats is maintained, supporting search, renaming, status verification, and enabling or disabling. The registry can be populated via three methods: a settings button, a webhook, or a CLI command. New chats require manual confirmation or can be approved automatically. Recipients are automatically disabled if persistent Telegram errors occur, such as bot blocking, removal from the chat, or insufficient permissions. Import and export of recipients are supported in CSV and JSON formats, with a preview step before saving.

Template Configuration

Message templates are editable and support variable substitution with a live preview feature. Three formatting modes are available: MarkdownV2, HTML, and plain text. Telegram-specific parameters allow disabling sound, blocking message forwarding, disabling link previews, and applying supergroup themes.

Diagnostics and Operations

The delivery log records key details for each event: event type, site, bot, recipient, HTTP status, error code, request duration, and values for retry_after and message_id.

The module provides detailed analytics on delivery success, including statistics for bots, HTTP status codes, and a top errors report. Problematic notifications can be returned to the queue individually or in batches. An administrative action log is maintained.

A module diagnostics page allows checking the state of tables, settings, the queue, and webhooks, and supports exporting reports in JSON and support bundles without secrets. Retention periods for all logs are configurable.

Security and Privacy

The bot token is stored encrypted or retrieved from an environment variable. Webhook secret rotation occurs without downtime: the previous value remains valid for a specified duration. The system includes protection against reprocessing identical update_ids. Personal data is automatically masked in logs and exports. User access rights can be restricted.

Admin Panel Interfaces

Section "Services → Telegram Notifications".

Section "Settings → Product Settings → Module Settings → Telegram Notifications".

When needed, General iT can implement “Telegram Notifications”, configure the module and verify it against the current website setup.