Setting up order status notifications in 1C-Bitrix Telegram

Configuring Order Status Notifications in Telegram for 1C-Bitrix

A customer places an order and waits for an email that ends up in spam. A Telegram notification arrives instantly and is read five times more often than email. In Bitrix, standard order notifications work via b_event_message and are sent by email. Adding Telegram means hooking into the order status change event and sending a message through the Telegram Bot API.

How Order Events Work in Bitrix

When an order status changes, Bitrix fires the OnSaleOrderStatusChange event. The standard notification mechanism (/bitrix/admin/posting_list.php) sends email. Telegram is connected as an additional channel via an event handler.

Creating a Telegram Bot for Notifications

A bot for order notifications is not conversational — it is push-only: it only sends, it does not accept commands. Create it via @BotFather:

/newbot
Name: MyShop Notifications
Username: myshop_orders_bot

You receive a token like 1234567890:AAHb-xxxxxx. The token is stored in the module settings or in /bitrix/.settings.php, not in template code.

The user must start a conversation with the bot (/start) so the bot can obtain their chat_id. To enable this, place a "Connect Telegram Notifications" button in the customer's personal account that opens the link https://t.me/myshop_orders_bot?start=uid_12345.

Saving the User's chat_id

// Bot webhook receives /start with a parameter
$update = json_decode(file_get_contents('php://input'), true);
$text = $update['message']['text'] ?? '';
$chatId = $update['message']['chat']['id'];

if (preg_match('/^\/start uid_(\d+)$/', $text, $matches)) {
    $userId = (int)$matches[1];

    // Save chat_id to the custom user field UF_TELEGRAM_CHAT_ID
    \Bitrix\Main\UserTable::update($userId, [
        'UF_TELEGRAM_CHAT_ID' => $chatId,
    ]);

    // Confirmation to the user
    TelegramApi::sendMessage($chatId, 'Telegram order notifications are now connected.');
}

Order Status Change Handler

// /local/php_interface/init.php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleOrderStatusChange',
    function (\Bitrix\Main\Event $event) {
        $order = $event->getParameter('ENTITY');
        $statusId = $order->getField('STATUS_ID');
        $userId = $order->getUserId();

        // Read the user's chat_id
        $user = \Bitrix\Main\UserTable::getById($userId)->fetch();
        $chatId = $user['UF_TELEGRAM_CHAT_ID'] ?? null;

        if (!$chatId) {
            return; // User has not connected Telegram
        }

        // Build message text based on status
        $messages = [
            'N' => 'Order #%d has been received and is awaiting processing.',
            'P' => 'Order #%d has been dispatched for delivery.',
            'F' => 'Order #%d is complete. Thank you for your purchase!',
            'X' => 'Order #%d has been cancelled.',
        ];

        $template = $messages[$statusId] ?? null;
        if (!$template) {
            return;
        }

        $text = sprintf($template, $order->getId());
        $text .= "\n\nDetails: " . SITE_SERVER_NAME . '/personal/orders/' . $order->getId() . '/';

        // Send via Telegram Bot API
        TelegramBotService::send($chatId, $text);
    }
);

Telegram Bot API Sender Class

class TelegramBotService
{
    private static string $token = '1234567890:AAHb-xxxxxx';

    public static function send(string $chatId, string $text, array $options = []): bool
    {
        $params = array_merge([
            'chat_id'    => $chatId,
            'text'       => $text,
            'parse_mode' => 'HTML',
        ], $options);

        $ch = curl_init('https://api.telegram.org/bot' . self::$token . '/sendMessage');
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($params),
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 5,
        ]);
        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true)['ok'] ?? false;
    }
}

The token is stored in config, not in code:

// /bitrix/.settings.php
'custom' => [
    'value' => [
        'telegram_bot_token' => '1234567890:AAHb-xxxxxx',
    ],
],

Setup Timeline

Creating the bot, the UF_TELEGRAM_CHAT_ID custom user field, the connection page in the personal account, and the order event handler — 6–10 hours.