Транспорты уведомлений (Telegram / MAX) (EcomLabs)

КРАТКО О МОДУЛЕ

Модуль отправляет уведомления о событиях Битрикс (почтовые и SMS-события) в
Telegram и MAX: шаблоны текстов, очередь с повторами, журнал, привязка чатов
пользователей к ботам, webhook'и, тестовые инструменты.

Меню в админке: «Транспорты уведомлений» → Шаблоны, Очередь, Журнал, Привязки,
Инструменты / Тест.

Настройки модуля: Настройки → Настройки продукта → Настройки модулей →
Транспорты уведомлений (Telegram / MAX).

ОПИСАНИЕ ВСЕХ НАСТРОЕК

Три вкладки: Общие, Telegram, MAX.

Общие

• Число попыток отправки — сколько раз повторять отправку из очереди при ошибке.

• TTL токена привязки (мин.) — срок жизни одноразового токена deep-link для
 привязки чата пользователя к боту.

• Размер пакета очереди — сколько заданий обрабатывает агент за один запуск.

• Предпочитаемый мессенджер — Telegram / MAX / «—» (без предпочтения). Используется, когда у пользователя несколько привязок.

Telegram

• Включить Telegram — вкл/выкл канал.

• Токен бота Telegram — токен от @BotFather.

• Имя бота (без @) — username для ссылок t.me/... (можно подтянуть через
 «Проверить бота» в Инструментах).

• Секрет webhook — secret_token для проверки входящих запросов Telegram.

• Отключить превью ссылок — disable_web_page_preview при отправке сообщений.

• Chat ID администратора — ручной chat_id для тестов и админ-уведомлений.

• Публичный webhook — только для чтения: URL вида /bitrix/tools/ecl_eventtransports_webhook_telegram.php

MAX

• Включить MAX — вкл/выкл канал.

• Access token MAX — токен бота платформы MAX.

• Имя бота MAX — для deep-link и отображения.

• Секрет webhook MAX — проверка входящих webhook.

• Chat ID администратора MAX — ручной ID.

• URL API MAX — по умолчанию https://platform-api2.max.ru

• Отключить проверку SSL — если нет доверия к цепочке сертификатов (в т.ч. сертификаты Минцифры).

• Шаблон deep link — шаблон ссылки привязки, плейсхолдеры #BOT# и #TOKEN#.

• Текст после успешной привязки — ответ бота после успешного bind.

• Текст, если payload без токена — приветствие/подсказка без токена.

• Публичный webhook — URL webhook MAX (только чтение).

ОПИСАНИЕ СТРАНИЦ И ВОЗМОЖНОСТЕЙ АДМИНКИ

Шаблоны (templates_list / templates_edit)

• Список шаблонов уведомлений по каналам (Telegram / MAX).

• Создание и редактирование: привязка к коду события Битрикс (SMS или почта), текст сообщения, активность.

• Коды событий подтягиваются из типов почтовых событий и SMS-событий сайта.

• Правило: один код события + один транспорт = один шаблон.

• При срабатывании обработчиков OnBeforeEventSend, OnBeforeEventAdd, OnBeforeSmsSend модуль ставит задание в очередь, если есть подходящий шаблон и привязка получателя.

Очередь (queue_list)

• Список заданий: канал, событие, пользователь, заказ, chat_id, статус (Новая / Повтор / Отправлено / Ошибка), число попыток, текст ошибки, дата.

• Действия: повторить отправку, удалить.

• Обрабатывается агентом: \Ecl\EventTransports\Service\QueueService::agent()

Журнал (log_list)

• История попыток отправки: успех/ошибка, канал, событие, chat_id, связь с записью очереди, дата.

• Удаление записей.

Привязки (bindings_list)

• Связки «пользователь Битрикс ↔ chat_id» в Telegram / MAX.

• Статус: активна / отключена.

• Удаление привязок.

Инструменты / Тест (tools)

• Отображение URL webhook для Telegram и MAX.

• Telegram:

   – проверить бота (getMe);
   – подписать webhook;
   – статус webhook;
   – удалить webhook.

• MAX:

   – подписать webhook;
   – инфо о боте (/me);
   – статус webhook
   – удаление webhook.

• Генерация ссылки привязки для указанного ID пользователя Битрикс и транспорта.

• Обновление статуса привязки, отвязка.

• Тестовая отправка произвольного текста привязанному пользователю.

• Ручная привязка по MAX user_id / Telegram chat_id (если webhook ещё не настроен).

Карточка пользователя (настройки пользователя)

• Вкладка «Мессенджеры»: статус привязок Telegram и MAX, кнопки «Привязать» / «Отвязать» (options_user_settings).

КОМПОНЕНТ ecl:eventtransports.bind

Название: «Привязка к Telegram / MAX»

Назначение: блок в личном кабинете / профиле для привязки и отвязки мессенджеров.

Параметры компонента

• Показывать Telegram (SHOW_TELEGRAM) — Y/N, по умолчанию Y.

• Показывать MAX (SHOW_MAX) — Y/N, по умолчанию Y.

Возможности

• Работает только для авторизованного пользователя.

• Показывает статус: привязан / не привязан, chat_id.

• Кнопки «Привязать» / «Отвязать» через AJAX (/bitrix/tools/ecl_eventtransports_user_bind_ajax.php).

• При «Привязать» может выдать deep-link на бота с одноразовым токеном (TTL задаётся в настройках модуля).

• После перехода в бота и подтверждения webhook фиксирует привязку в БД.

Подключение: визуальный редактор или $APPLICATION->IncludeComponent('ecl:eventtransports.bind', '', [...]);

ОПИСАНИЕ РАБОТЫ ПРОВЕРКИ

Проверка токена бота

В разделе «Инструменты»:

• «Проверить Telegram-бота (getMe)»

• «Инфо о боте MAX (/me)»

Успешный ответ означает, что токен верный и API доступен. Для Telegram имя бота может автоматически сохраниться в настройки модуля.

Требование HTTPS

Webhook Telegram принимается только по HTTPS. При HTTP URL выдаётся ошибка о необходимости HTTPS.

Подписка webhook

• Telegram: setWebhook на публичный URL модуля с secret_token из настроек.

• MAX: подписка на URL модуля с секретом из настроек.

Статус webhook, last error, pending updates — через кнопки «Статус webhook».

Входящие webhook

Скрипты:

• /bitrix/tools/ecl_eventtransports_webhook_telegram.php

• /bitrix/tools/ecl_eventtransports_webhook_max.php

Проверяют секрет (и связанные проверки модуля), обрабатывают start/payload с токеном привязки, создают или обновляют запись привязки пользователя.

Тестовая отправка

Текст уходит в chat_id привязанного пользователя. Это проверка полного пути: Настройки → API мессенджера → привязка → доставка.

Очередь и агент

Событие Битрикс → найден шаблон → запись в очередь → агент с учётом числа попыток и размера пакета → запись в журнал (успех или ошибка).