Интеграция с корпоративным чатом на matrix.org

Как только в 2024ом заговорили про блокировку Telegram, наше руководство начало беспокоиться, где мы будем в дальнейшем общаться. Выбор почему-то пал на matrix.org. Переезд давался сложно, мы сопротивлялись как могли, но нашлись и положительные стороны данной штуки. Я упомяну плюсы списочно, а потом расскажу какие мастхэв можно делать прямо из 1С и что можно предложить бизнесу реализовать на базе вот таких мессенджеров.

Сначала минусы:

1) свободное распространение. как следствие — разбирайся с документацией сам. Если найдешь вообще. А ещё она не актуальна. Точнее вот тут актуальна, а здесь актуальна только на половину. А тут мы пирожки пекли. а здесь рыбу заворачивали.

2) дизайн. 

3) не всегда сообщит тебе о входящем сообщении, звонке. А если сообщит то не всегда у тебя получится его принять. А если получится и ты в блютуз наушниках — ты ещё хлопот получишь. В общем работает, но не стабильно.

Теперь плюсы:

1) Бесплатно, ну или почти. 

Мы все не любим платить, так что если не считать стоимости серверов, времени админа и нашей собственной боли он интерфейса данного приложения — оно бесплатно. Вы можете абсолютно свободно скачать ПО с сайта https://matrix.org/ установить к себе на сервера и развернуть у себя базу. Пару взмахов бубном, две сотни кругов вокруг gitHub елки — и оно ваше.

2) Кажется, это называлось кроссплатформенность. 

Я не могу сказать в адрес их интерфейса много положительных моментов, но у них есть:

 — доступ через веб интерфейс в любом браузере 

— доступ через Андроид приложение

— доступ c iOS

—  и ещё много всего, чем мне не удалось воспользоваться, но это описано тут

3) Понятный интерфейс.

Самое сложное для пользователей — авторизация, она же регистрация. Все остальное проще даже чем в ВК или одноклассники. Вот тут действительно интуитивный, деревянный интерфейс. Даже аватарку можно себе настроить и чатик с друзьяшками по работе. Всё чем пользоваться будут каждый день вынесено большими кнопками. Все тонкие настройки запрятаны, если есть вообще.

4) Защищенные чаты.

Да, наше руководство всегда мечтает об этом — чат, в котором они могут писать и никто это не прочтет. даже ваш самый главный админ. Дело в том, что все остальные чаты можно легко прочесть, как только получили доступ к базе — они ничем не защищены и хранятся в таблице с указанием адреса комнаты, отправителя и отметкой времени, то есть ваше руководство спокойно может потребовать с админа предоставить им, о чем там общается ваш оператор с коллегами в свое рабочее время, и что он о своем начальнике думает. Это ли не мечта?

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

Включается шифрование на чате в настройках комнаты.

5) можно звонить

и даже видео звонки есть, но без многопользовательских видеоконференций. И даже те есть в альфа тестировании вроде, но я не пользовалась.

6) У них есть Api с документацией.

Ну как документацией.. Явно немного устаревшая, но если покопаться то разобраться с ней можно. Запросы, JSON, и спасибо им за это 🙂

Identity Service API

Application Service API 

Federation API   

И собственно то Api, которым вам потребуется использовать, если вы решите обращаться к вашему серверу из 1С: Client-Server API

 

Расширение, приложенное к публикации тестировалось на УТ11 и использует некоторые типовые функции из пользовательских общих модулей БСП, связанных с формированием рандомного пароля.

ОбщийМодуль.Matrix_Интеграция — содержит запросы к API, которые я описываю в данной статье.

Справочник.ПользователиЧата, РегистрСведений.АвторизацияОператоров  — метаданные для наглядности, используются в некоторых функциях общего модуля. Вы можете использовать их, или перенести реквизиты справочника в типовой справочник пользователей. Я завела отдельный для удобства настройки прав доступа и мобильности кода

Обработка.ШаблоныИспользования предназначена для демонстрации военной мощи использования функций общего модуля.

По коду встречается строка "<YourServerName>" перед тестированием рекомендую заменить её на имя вашего сервера, иначе чуда не произойдет.

Реализованные функции:

Формат ИДПользователя     "@<Login>:<RegServer>"  — пользователь зарегистрированный на общем сервере будет выглядеть примерно как  @cheeky_monkey:matrix.org, всегда можно посмотреть в профиле.

Формат ИДКомнаты             "!<КодКомнаты>:<YourServerName>"  — например !21d41d8cd:matrix.org , всегда можно посмотреть в адресной строке в открытом окне чата из браузера, или в настройках чата, если вы работаете из мобильного приложения.

 

Функции:

СоздатьПользователя — на вход получает строку с логином будущего пользователя, убирает из него все непотребные знаки, переводит на латиницу, выставляет в нижний регистр и создает пользователя на сервере чата. На выход отдает структуру с булево success и текстом ошибки(в случае неудачи) или логином и паролем, в случае успеха. Демонстрация функции есть в обработке ШаблоныИспользования.

СоздатьКомнату(ИмяКомнаты,ТемаЧатика,Токен, МассивПользователей,ДоступККомнате = "private")

Токен — ваш токен, вы автоматически назначаетесь администратором.

Имя комнаты — которое будут видеть все.

ТемаЧатика -подпись мелким шрифтом под темой чата.

Массив пользователей — массив тех, кого необходимо добавить сразу в момент создания чата. в массив добавляем строки с ИДПользователя. Автора чата указывать не нужно — он добавится автоматом. Массив может быть пустым.

АвторизоватьсяНаСервере — на вход ждет структуру содержащую свойства Login и Pass. У меня есть справочник с такими реквизитами — я просто кидаю на вход ссылку на элемент справочника. На выход процедура возвращает вам Токен. Если чуда не произошло — пришлет пустую строку.

ПолучитьУчастниковКомнаты(ИДКомнаты,Токен) — если вы пригласили пользователя в комнату, а он еще не принял приглашение — он ещё не участник. Возвращает массив ИДПользователей

ПрисоединитьсяКГруппе(ИДКомнаты,Токен) — если вам пришло приглашение в группу, вы можете его принять и присоединиться к группе. 

ПолучитьСообщенияИзЧата(ИДКомнаты,Токен,КоличествоСообщений=0,filter = "") — получает ограниченное количество последних сообщений чата. Если не укажете сколько должен получить — я по умолчанию задаю 1000. Фильтр — ограничивает типы сообщений. В документации достаточно многословно про это написано. Я ограничилась только одним типом m.room.message, именно он будет по умолчанию, если вы пришлете в этот параметр пустую строку. Возвращает структуру и тут надо рассказать чуть подробнее.

Структура имеет вид:

{
"start": "t47429-4392820_219380_26003_2265", //внутренняя отметка времени крайнего сообщения из выбранных по всей видимости.
"end": "t47409-4357353_219380_26003_2265",
"chunk": [                                   //массив сообщений
{
"origin_server_ts": 1444812213737,       //отметка времени, в юникс формате? можно рассчитать когда отправлено
"sender": "@alice:example.com",
"event_id": "$1444812213350496Caaaa:example.com", //UID сообщения. с его помощью можно отвечать на сообщения, удалять их, редактировать.
"content": {
"body": "hello world",
"msgtype": "m.text"
},
"room_id": "!Xq3620DUiqCaoxq:example.com",
"type": "m.room.message",                 //наш отфильтрованный тип сообщений. Если не фильтровать - здесь может быть звонок, смена названия комнаты, добавление пользователей и многое другое.
"age": 1042                               //ещё одна отметка времени, по всей видимости отображает как давно оно отправлено
}
]
}

 

ПолучитьСобытия(Токен, since = "", filter="") — возвращает вам все доступные для вас события. Здесь будут сообщения в чатах, звонки, и абсолютно всё, что вы можете увидеть, использовать и имеете доступ.

Вот здесь вам точно пригодятся фильтры и понимание как работает тот самый внутренний формат времени. При стартовом вызове этой процедуры я рекомендую прислать вам пустую строку в поле since — пользователю вернётся всё, что происходило на сервере, и текущая отметка времени(next_batch) — её необходимо сохранить в настройках пользователя, чтобы в следующий раз запросить дельту, а не всё события с начала времен.

Структура сообщений, которую возвращает сервер достаточно разветвленная, чтобы в ней плутать. Если у вас большой поток сообщений планируется — имеет смысл разобраться в фильтрах. Я в комментариях над процедурой в общем модуле предлагаю вариант сборки простейшего фильтра. Использовать его или пробовать собрать свой — решать вам. Вот он:

ТСтрукт = Новый структура();
ТСтрукт.Вставить("room",Новый структура());
ТСтрукт.room.Вставить("timeline",Новый структура());

ТМассив = Новый массив();
ТМассив.Добавить("m.room.message");
ТСтрукт.room.timeline.Вставить("types",ТМассив);

ТСтрукт.room.Вставить("state",Новый структура());

ТМассив = Новый массив();
ТМассив.Добавить("m.room.member");
ТСтрукт.room.state.Вставить("types",ТМассив);

ТСтрукт.room.Вставить("ephemeral",Новый структура());

ТМассив = Новый массив();
ТМассив.Добавить("m.*");
ТСтрукт.room.ephemeral.Вставить("not_types",ТМассив);

ТСтрукт.room.Вставить("account_data",Новый структура());

ТМассив = Новый массив();
ТМассив.Добавить("*");
//ТМассив.Добавить("m.fully_read");           //на него почему то не срабатывает!!!
ТСтрукт.room.account_data.Вставить("not_types",ТМассив);

ТМассив = Новый массив();
ТМассив.Добавить("type");
ТМассив.Добавить("content");
ТМассив.Добавить("sender");
ТСтрукт.Вставить("event_fields",ТМассив);

ЗаписьJSON=Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON,ТСтрукт);
filter=ЗаписьJSON.Закрыть();

Вот здесь достаточно полно описано построение фильтра

А вот тут актуальный вид документации по фильтрам для функции синхронизации

 

Процедуры:

УстановитьИмяПользователю(ИДПользователя, Имя, Токен) — устанавливает пользователю удобочитаемое имя. Логин у вас user1, а все будут видеть, что общаются с Сергеем Геннадьевичем. Демонстрация функции есть в обработке ШаблоныИспользования.

Токен — пользователя, которому планируем изменить представление. 

ДобавитьПользователяВЧат(ИДКомнаты, Токен, ИДПользователя) — высылает приглашение пользователю на добавление в чат.

Токен — токен администратора чата.

ИДПользователя — тот кого мы хотели бы добавить. 

УдалитьПользователяИзЧата(ИДКомнаты,Токен,ИДПользователя,Причина="")

ОтправитьСообщениеВЧат(ИДКомнаты,Токен,ТекстСообщения) — матрикс позволяет отправлять не только текстовые сообщения, но и видео, аудио. но я привожу функцию отправки только текста.

 

Зачем интеграция с 1С?

Потому что могу. А если серьёзно, то есть несколько полезных кейсов:

1) проходит регламент и он отрабатывает с ошибкой. Как часто в течение дня я загляну в статус регламентных заданий? ну хорошо если пару раз за день, а так робот сам мне напишет в чатик, что что-то пошло не так. 

2) а пусть пользователей известит, что кто-то внес правки в документ из закрытого периода и всем расскажет, кто виновник торжества. 

3) у нас есть несколько событий в 1С и на различных других внешних системах обработки данных, которые надо контролировать. Например потерялся в пути заказ. Или заказ не можем вручить уже неделю. Писать ответственным на почту — вероятность прочтения близка к нулю, в этой почте у них и без того свалка. А вот чат они на удивление быстро обрабатывают. 

4) интеграция с маркетплейс. Видели как у приложений доставки есть окошко общения с оператором? мы реализовали его через matrix+маркетплейс+1С+наши операторы call-центра.