Setting up transactional notifications in 1C-Bitrix messengers

Setting Up Transactional Notifications to Messengers in 1C-Bitrix

A transactional notification is a message sent in response to a specific user action: placing an order, making a payment, a status change, or a refund. In 1C-Bitrix the standard mechanism for such notifications works through b_event_message and email. Adding messengers (Telegram, Viber, WhatsApp) requires a separate architecture: a single event handler, an abstract sender interface, and routing based on user preferences.

Types of Transactional Events in Bitrix

Key events of the sale module:

• OnSaleOrderSaved — order created
• OnSaleOrderStatusChange — status change
• OnSaleOrderPaid — payment confirmed
• OnSaleOrderCanceled — order cancelled
• OnSaleShipmentTracking — delivery tracking update

main module:

• OnAfterUserRegister — user registration

Architecture: Unified Notification Dispatcher

Instead of attaching a separate handler for each messenger, we build a dispatcher:

// /local/lib/Notifications/Dispatcher.php
namespace Local\Notifications;

class Dispatcher
{
    private static array $channels = [
        'telegram' => TelegramChannel::class,
        'viber'    => ViberChannel::class,
        'whatsapp' => WhatsAppChannel::class,
        'email'    => EmailChannel::class,
    ];

    public static function send(int $userId, string $event, array $data): void
    {
        $prefs = self::getUserPreferences($userId);

        foreach ($prefs as $channelName => $enabled) {
            if (!$enabled) {
                continue;
            }

            $channelClass = self::$channels[$channelName] ?? null;
            if (!$channelClass) {
                continue;
            }

            try {
                /** @var ChannelInterface $channel */
                $channel = new $channelClass($userId);
                $channel->send($event, $data);
            } catch (\Exception $e) {
                // Log error, do not interrupt delivery to other channels
                \Bitrix\Main\Diag\Debug::writeToFile(
                    "Notification error [{$channelName}]: " . $e->getMessage(),
                    '', '/local/logs/notifications.log'
                );
            }
        }
    }

    private static function getUserPreferences(int $userId): array
    {
        $user = \Bitrix\Main\UserTable::getById($userId)->fetch();
        return [
            'telegram' => !empty($user['UF_TELEGRAM_CHAT_ID']) && $user['UF_NOTIFY_TELEGRAM'] === '1',
            'viber'    => !empty($user['UF_VIBER_USER_ID']) && $user['UF_NOTIFY_VIBER'] === '1',
            'whatsapp' => !empty($user['UF_PHONE']) && $user['UF_NOTIFY_WHATSAPP'] === '1',
            'email'    => true, // email is always enabled as a fallback
        ];
    }
}

Channel Interface and Message Templates

// /local/lib/Notifications/ChannelInterface.php
namespace Local\Notifications;

interface ChannelInterface
{
    public function send(string $event, array $data): void;
}

Message templates are kept separate from channel logic:

// /local/lib/Notifications/Templates.php
namespace Local\Notifications;

class Templates
{
    private static array $templates = [
        'order_created' => [
            'text' => 'Order #{{ORDER_ID}} has been placed for {{TOTAL}} {{CURRENCY}}.',
        ],
        'order_paid' => [
            'text' => 'Payment for order #{{ORDER_ID}} confirmed. Your order is being prepared for shipment.',
        ],
        'order_shipped' => [
            'text' => 'Order #{{ORDER_ID}} has been dispatched. Tracking: {{TRACKING_CODE}}.',
        ],
        'order_delivered' => [
            'text' => 'Order #{{ORDER_ID}} has been delivered. Thank you for your purchase!',
        ],
        'order_canceled' => [
            'text' => 'Order #{{ORDER_ID}} has been cancelled.',
        ],
    ];

    public static function render(string $event, array $data): string
    {
        $template = self::$templates[$event]['text'] ?? '';
        foreach ($data as $key => $value) {
            $template = str_replace('{{' . $key . '}}', $value, $template);
        }
        return $template;
    }
}

Registering Event Handlers

// /local/php_interface/init.php
use Local\Notifications\Dispatcher;

$em = \Bitrix\Main\EventManager::getInstance();

// Order created
$em->addEventHandler('sale', 'OnSaleOrderSaved', function (\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    if (!$order->isNew()) {
        return;
    }
    Dispatcher::send($order->getUserId(), 'order_created', [
        'ORDER_ID' => $order->getId(),
        'TOTAL'    => number_format($order->getPrice(), 2, '.', ' '),
        'CURRENCY' => $order->getCurrency(),
    ]);
});

// Status change
$em->addEventHandler('sale', 'OnSaleOrderStatusChange', function (\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    $statusId = $order->getField('STATUS_ID');

    $eventMap = [
        'P' => 'order_shipped',
        'F' => 'order_delivered',
        'X' => 'order_canceled',
    ];

    $notifyEvent = $eventMap[$statusId] ?? null;
    if (!$notifyEvent) {
        return;
    }

    $data = ['ORDER_ID' => $order->getId(), 'TRACKING_CODE' => ''];
    if ($notifyEvent === 'order_shipped') {
        // Get tracking number from shipment
        $shipment = $order->getShipmentCollection()->getNotSystemItems()->current();
        $data['TRACKING_CODE'] = $shipment?->getField('TRACKING_NUMBER') ?? 'pending';
    }

    Dispatcher::send($order->getUserId(), $notifyEvent, $data);
});

Managing Subscriptions in the User Account Area

The user chooses their preferred channels at /personal/notifications/:

• Checkboxes "Notifications in Telegram / Viber / WhatsApp"
• Channel connection buttons (deep link / phone number input)
• Preview of sample notifications

Settings are stored in user fields UF_NOTIFY_TELEGRAM, UF_NOTIFY_VIBER, UF_NOTIFY_WHATSAPP (type "Yes/No").

Message Queue

Synchronous delivery to three messengers on every status change adds latency to order processing. For high-load scenarios — an asynchronous queue:

// Instead of a direct call — push to queue
Queue::push('notification', [
    'user_id' => $userId,
    'event'   => $notifyEvent,
    'data'    => $data,
    'created' => time(),
]);

A worker processes the queue and makes the actual API requests to messenger services. A Bitrix agent as a simple queue option — checks the task table every minute.

Setup Timeline

Notification dispatcher with Telegram + Viber support, templates for 5 events, subscription management page in the user account area, without a queue (synchronous) — 2–3 business days. With an asynchronous queue and three messengers — 4–6 business days.