Розробка Telegram-каналу повідомлень про замовлення 1С-Бітрікс

Розробка Telegram-каналу сповіщень про замовлення 1С-Бітрікс

Telegram-канал сповіщень про замовлення — це не те саме, що бот з особистими повідомленнями. Канал призначений для команди: менеджери, оператори складу, кур'єри отримують сповіщення про нові замовлення, зміни статусів та критичні події у спільний потік. Це швидше за email і не вимагає від кожного співробітника підключення особистого бота. Розробка такого каналу — архітектурне завдання з кількома неочевидними нюансами на стороні Бітрікс.

Telegram-канал vs Telegram-бот: різниця в реалізації

Особистий бот — повідомлення надходять на chat_id конкретного користувача. Потрібен opt-in, потрібно зберігати chat_id кожного співробітника.

Канал — повідомлення публікуються в каналі, всі підписники бачать їх одночасно. Бот має бути доданий до каналу як адміністратор з правом публікації. chat_id каналу — статичний, не змінюється.

Група/супергрупа — гібрид: співробітники можуть відповідати, обговорювати замовлення, бот публікує події. Для команди — переважніше за канал.

Для сповіщень про замовлення частіше обирають супергрупу: менеджер може відповісти на повідомлення «приймаю» або додати коментар прямо в чат.

Схема роботи

[Подія в Бітрікс] → [Обробник події] → [Форматування повідомлення]
       ↓
[Telegram Bot API: sendMessage / sendPhoto]
       ↓
[Канал / Група команди]

Бот — технічний акаунт з токеном. Канал/група — місце отримання. Бот додається до каналу/групи через @telegram → Додати учасника → @your_bot.

Форматування повідомлень про замовлення

Telegram підтримує HTML та Markdown. Для замовлень — структуроване HTML-повідомлення:

class OrderNotificationFormatter
{
    public static function newOrder(\Bitrix\Sale\Order $order): string
    {
        $basket = $order->getBasket();
        $props = $order->getPropertyCollection();

        $name  = $props->getPayerName()?->getValue() ?? 'Не вказано';
        $phone = $props->getPhone()?->getValue() ?? '—';
        $email = $props->getUserEmail()?->getValue() ?? '—';

        $itemLines = [];
        foreach ($basket as $item) {
            $itemLines[] = sprintf(
                '  • %s × %d = %s',
                htmlspecialchars($item->getField('NAME')),
                (int)$item->getQuantity(),
                number_format($item->getFinalPrice(), 0, '.', ' ')
            );
        }

        $deliveryName = $order->getDeliverySystemName() ?? 'Не обрано';
        $paySystemName = $order->getPaySystemName() ?? 'Не обрано';

        return sprintf(
            "🛒 <b>Нове замовлення #%d</b>\n\n" .
            "👤 %s\n" .
            "📞 %s\n" .
            "✉️ %s\n\n" .
            "<b>Склад:</b>\n%s\n\n" .
            "💰 <b>Разом: %s</b>\n" .
            "🚚 %s\n" .
            "💳 %s\n\n" .
            "<a href=\"https://%s/bitrix/admin/sale_order_detail.php?ID=%d\">Відкрити в адмінці</a>",
            $order->getId(),
            htmlspecialchars($name),
            htmlspecialchars($phone),
            htmlspecialchars($email),
            implode("\n", $itemLines),
            number_format($order->getPrice(), 0, '.', ' '),
            htmlspecialchars($deliveryName),
            htmlspecialchars($paySystemName),
            $_SERVER['HTTP_HOST'],
            $order->getId()
        );
    }

    public static function statusChange(\Bitrix\Sale\Order $order, string $oldStatus): string
    {
        $statusList = \CSaleStatus::GetListArray();
        $oldName = $statusList[$oldStatus]['NAME'] ?? $oldStatus;
        $newName = $statusList[$order->getField('STATUS_ID')]['NAME'] ?? $order->getField('STATUS_ID');

        return sprintf(
            "🔄 <b>Замовлення #%d</b>: %s → <b>%s</b>",
            $order->getId(),
            htmlspecialchars($oldName),
            htmlspecialchars($newName)
        );
    }

    public static function lowStock(int $productId, string $productName, float $quantity): string
    {
        return sprintf(
            "⚠️ <b>Мало товару:</b> %s\nЗалишок: %s шт.\nID: %d",
            htmlspecialchars($productName),
            number_format($quantity, 0),
            $productId
        );
    }
}

Обробник подій з відправкою в канал

// /local/php_interface/init.php
use Local\Telegram\ChannelBot;
use Local\Telegram\OrderNotificationFormatter;

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

// Нове замовлення
$em->addEventHandler('sale', 'OnSaleOrderSaved', function (\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    if (!$order->isNew()) {
        return;
    }

    $message = OrderNotificationFormatter::newOrder($order);
    ChannelBot::post($message);
});

// Зміна статусу
$em->addEventHandler('sale', 'OnSaleOrderStatusChange', function (\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    $oldStatus = $event->getParameter('OLD_STATUS');

    $message = OrderNotificationFormatter::statusChange($order, $oldStatus);
    ChannelBot::post($message);
});

Клас відправки в канал

// /local/lib/Telegram/ChannelBot.php
namespace Local\Telegram;

use Bitrix\Main\Config\Configuration;

class ChannelBot
{
    private static function getConfig(): array
    {
        return Configuration::getValue('telegram_channel') ?? [];
    }

    public static function post(string $text, array $options = []): ?array
    {
        $config = self::getConfig();
        $token  = $config['bot_token'] ?? '';
        $chatId = $config['channel_id'] ?? ''; // наприклад: -1001234567890

        if (!$token || !$chatId) {
            return null;
        }

        $payload = array_merge([
            'chat_id'                  => $chatId,
            'text'                     => $text,
            'parse_mode'               => 'HTML',
            'disable_web_page_preview' => true,
        ], $options);

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

        $raw      = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            \Bitrix\Main\Diag\Debug::writeToFile(
                "Telegram channel error {$httpCode}: {$raw}",
                '', '/local/logs/telegram.log'
            );
            return null;
        }

        return json_decode($raw, true);
    }

    public static function postPhoto(string $photoUrl, string $caption = ''): ?array
    {
        $config = self::getConfig();
        return self::callApi('sendPhoto', [
            'chat_id'   => $config['channel_id'],
            'photo'     => $photoUrl,
            'caption'   => $caption,
            'parse_mode' => 'HTML',
        ]);
    }

    private static function callApi(string $method, array $payload): ?array
    {
        $config = self::getConfig();
        $ch = curl_init('https://api.telegram.org/bot' . $config['bot_token'] . '/' . $method);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($payload),
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 5,
        ]);
        $raw = curl_exec($ch);
        curl_close($ch);
        return json_decode($raw, true);
    }
}

Конфігурація в /bitrix/.settings.php:

'telegram_channel' => [
    'value' => [
        'bot_token'  => '7654321:AAbcdef...',
        'channel_id' => '-1001234567890',
    ],
],

channel_id для каналу починається з -100. Дізнатися його можна, переславши повідомлення з каналу в @userinfobot.

Додаткові події для операційного каналу команди

Окрім замовлень, в операційний канал корисно транслювати:

• Низький залишок товару — тригер через агент Бітрікс, який раз на годину перевіряє b_catalog_store_product WHERE AMOUNT < THRESHOLD
• Помилки експорту в 1С — лог b_event_log з типом SALE_EXCHANGE_ERROR
• Велике замовлення — якщо b_sale_order.PRICE > N, окреме повідомлення з позначкою
• Покинутий кошик більше 3 годин — за запитом до b_sale_basket з фільтром за датою

Терміни розробки