Wialon Message Hub — шлюз доставки уведомлений Wialon в Telegram и MAX

Wialon Message Hub (внутреннее техническое название — Wialon Message Gateway, WMG) — промежуточный сервис Exzotron, который забирает сработавшие уведомления из Wialon Local и доставляет их конечным пользователям в Telegram и российском мессенджере MAX согласно назначенным им правам, независимо от штатных возможностей доставки самого Wialon.

1. Проблема#

Wialon Local — распространённая локальная система спутникового мониторинга транспорта. Она умеет формировать разнообразные уведомления: включение зажигания, движение, превышение скорости, потеря и восстановление связи с терминалом, разряд аккумулятора, перезагрузка терминала, срабатывания датчиков (температура, уровень топлива, геозоны) и другие события, настраиваемые администратором Wialon.

Штатные каналы доставки уведомлений Wialon не всегда покрывают то, что реально нужно конкретному заказчику. В частности, возникает необходимость доставлять уведомления через мессенджеры, которыми диспетчеры и ответственные лица пользуются постоянно — Telegram и российский мессенджер MAX — с гибким управлением тем, кто из сотрудников какие типы уведомлений получает, без необходимости открывать сам Wialon.

2. Задача#

Построить промежуточный интеграционный сервис, который:

• подключается к произвольному числу компаний-клиентов Wialon Local независимо друг от друга;
• регулярно опрашивает сработавшие уведомления по каждой компании;
• определяет получателей внутри компании исходя из назначенных им прав на конкретные типы уведомлений;
• доставляет сообщения в Telegram и/или MAX, в зависимости от того, где пользователь зарегистрирован;
• даёт администратору единую панель управления компаниями, пользователями, правами и состоянием доставки;
• переживает временную недоступность Wialon, Telegram или MAX, не теряя события и не задваивая отправку.

3. Как это работает#

Wialon Message Hub — четыре взаимодействующих процесса на общей базе PostgreSQL: Web UI (административная панель — компании, пользователи, права, журнал событий, диагностика подключений), Collector (фоновый процесс, по расписанию опрашивающий Wialon Local каждой активной компании и складывающий новые события в базу), Dispatcher (фоновый процесс, раскладывающий новые события по получателям согласно их правам и отправляющий сообщения в Telegram/MAX, с повторными попытками при временных сбоях) и сама PostgreSQL — единственное общее хранилище состояния между всеми процессами. Все компоненты развёрнуты как отдельные Docker-контейнеры за общим nginx-прокси.

1. Администратор подключает компанию: указывает адрес сервера Wialon Local и учётные данные (токен или логин/пароль), при необходимости — токены Telegram- и MAX-ботов.
2. Collector этой компании авторизуется в Wialon, периодически запрашивает список объектов и сработавшие уведомления за прошедшее с последнего опроса время, пишет новые события в базу с защитой от повторной записи.
3. Dispatcher находит новые события, определяет их тип, ищет пользователей компании, которым назначено право на этот тип уведомления и которые зарегистрированы и активны в Telegram или MAX, формирует текст сообщения (с тематической иконкой и, если у события есть координаты, — картой местоположения) и ставит в очередь отправки.
4. Очередь обрабатывается с повторными попытками по расписанию при временных сбоях канала доставки; окончательные ошибки (например, пользователь заблокировал бота) фиксируются без бесконечных повторов.
5. Пользователь регистрируется в канале доставки самостоятельно, командой /start в соответствующем боте; администратор одобряет регистрацию и назначает нужные типы уведомлений через веб-панель.

4. Работа с несколькими компаниями#

Одна инсталляция Wialon Message Hub одновременно обслуживает произвольное число независимых компаний. У каждой — собственные учётные данные Wialon, собственные Telegram- и MAX-боты, собственный справочник типов уведомлений, собственные пользователи и права, раздельно управляемые статусы сбора (Collector) и рассылки (Dispatcher). Данные компаний друг от друга изолированы на уровне запросов к базе.

5. Подключение компании: Wialon, Telegram, MAX#

Все настройки компании — адрес и учётные данные Wialon, токены Telegram- и MAX-ботов, правила регистрации пользователей — собраны в одной форме на панели администратора.

Подключение к Wialon Local выполняется по Remote API (HTTP/JSON): основной способ авторизации — постоянный API-токен (token/login), запасной — логин/пароль (login/login). Токен и пароль хранятся в базе в зашифрованном виде.

Для случаев, когда у пользователя Wialon нет отдельного доступа по API (частая ситуация на локальных инсталляциях), реализовано автоматическое получение токена по логину и паролю через управляемый headless-браузер, повторяющий обычный веб-вход — единственный надёжный способ для тех версий Wialon Local, где страница входа формирует служебные поля через JavaScript и прямой HTTP-запрос к API входа недоступен пользователю.

Telegram-бот для компании создаётся штатным способом через официальный бот @BotFather (команда /newbot); Wialon Message Hub не создаёт ботов сам — только подключает уже созданный бот по токену. Пользователь запускает бота командой /start, при необходимости указывает код регистрации компании, после чего администратор одобряет регистрацию и назначает права на типы уведомлений.

Интеграция с MAX реализована по протоколу MAX Bot API (собственный HTTP-клиент, long-polling получение сообщений). Бот MAX создаётся средствами платформы MAX Business — там же выдаётся токен доступа. Логика регистрации пользователя зеркальна Telegram, но реализована отдельно — с учётом того, что один MAX-бот, в отличие от Telegram, может технически обслуживать сразу несколько компаний.

6. Collector и обработка событий#

Collector — процесс, отдельно для каждой активной компании авторизующийся в Wialon и с заданным интервалом запрашивающий сработавшие уведомления (messages/load_interval) по каждому объекту компании. Точкой отсчёта служит момент последней успешной синхронизации; при первом подключении компании она задаётся администратором явно. Между опросами окно намеренно немного перехлёстывается, чтобы не потерять события на границе, а повторная запись исключается уникальным ключом события в базе.

Ошибка по одному объекту или временная недоступность Wialon не останавливают сбор по остальным объектам и компаниям — Collector восстанавливает сессию автоматически на следующем цикле.

Каждое сработавшее уведомление сопоставляется со справочником типов уведомлений компании (синхронизируется отдельно из Wialon), формируется читаемый текст с тематической иконкой (по ключевым словам в названии уведомления — слив, заправка, скорость, геозона, тревога, потеря связи и т. д.), и, если у события есть географические координаты, — отдельно отправляется карта с меткой местоположения.

7. Dispatcher#

Dispatcher раскладывает новые события по получателям (пользователям, у которых есть право на конкретный тип уведомления и активная регистрация в канале) и отправляет сообщения. Очереди Telegram и MAX полностью независимы: пользователь, зарегистрированный в обоих каналах, получит сообщение дважды, независимо друг от друга. При временных ошибках канала (ограничение частоты отправки, недоступность API) применяется расписание повторных попыток с нарастающей задержкой; окончательные ошибки (заблокированный бот, несуществующий чат) фиксируются без повторов.

8. Пользователи и права#

В веб-панели пользователи Telegram и MAX компании отображаются на отдельных вкладках. Администратор видит статус регистрации (NEW / APPROVED / BLOCKED), может одобрить или заблокировать пользователя, включить/выключить получение сообщений независимо от статуса регистрации, переименовать (задать понятное отображаемое имя) и настроить его права — по каждому типу уведомления отдельным переключателем.

Права назначаются на тип уведомления, а не на конкретный объект (транспортное средство) или группу объектов Wialon — если пользователю разрешён тип «Нарушение скоростного режима», он получит такое уведомление по любому объекту компании, для которого оно сработает.

Один и тот же человек может быть зарегистрирован в обоих каналах одновременно (это разные, независимые записи) и будет получать назначенные ему уведомления в оба канала сразу.

9. Контроль доставки и журнал событий#

Для каждого события в журнале виден статус (NEW / SENT / ERROR), число успешно отправленных сообщений и число ошибок по всем получателям этого события, с фильтрами по датам, объекту, статусу и тексту сообщения. Администратор может в любой момент проверить подключение к Wialon, Telegram и MAX отдельными кнопками и выполнить внеплановую синхронизацию, не дожидаясь очередного цикла фонового Collector.

Отдельный общий «Журнал» на верхней панели фиксирует системные события (ошибки авторизации, сбои сети, результаты синхронизации) по всем компаниям сразу — полезен, когда причина не очевидна из карточки конкретной компании.

10. Надёжность#

Ошибка одной компании, одного объекта или одного получателя не блокирует работу остальных — изоляция ошибок реализована на всех уровнях (Collector — по объекту и по компании, Dispatcher — по одному сообщению в очереди). Повторная запись одного и того же события в базу исключена уникальным ограничением. Временные сбои каналов доставки обрабатываются повторными попытками по расписанию.

11. Безопасность#

Учётные секреты (пароли и токены Wialon, Telegram, MAX) хранятся в базе в зашифрованном виде, ключ шифрования — только в конфигурации сервера. В интерфейсе секреты показываются только частично замаскированными. Пароль администратора хранится хэшированным, необратимо (Argon2id); при первом запуске учётная запись admin создаётся с пустым паролем, вход с которым возможен только один раз — сразу после него система принудительно требует установить постоянный пароль.

12. Внедрение#

Подключение новой компании — короткая последовательность из шести шагов, от развёртывания сервиса в инфраструктуре заказчика до выхода в продуктивную работу.

13. Итог#

Wialon Message Hub закрывает разрыв между тем, что умеет формировать Wialon Local, и тем, каким каналом связи реально пользуются сотрудники заказчика. Решение уже эксплуатируется на нескольких компаниях с реальной доставкой в Telegram и MAX, устойчиво к типовым сбоям интеграции (протухание сессии Wialon, временная недоступность каналов доставки, ошибки по отдельным объектам) и спроектировано так, чтобы подключение нового канала доставки в будущем не требовало переработки ядра системы.