Всем привет!
В данной статье будут показаны некоторые отличия между реализациями интеграций с Max и Telegram.
Интеграция с Telegram нами была реализована давно и включает в себя:
- отправка и получение сообщений и вложений.
- запуск и контроль процессов.
- создание, контроль, выполнение задач.
- конструктор произвольных чат-ботов.
Идентичный функционал реализован и для мессенджера Max.
В процессе реализации нами были отмечены некоторые отличия между API Max и Telegram, которые требовали внимания и реализации отдельных механизмов, чтобы обеспечить идентичность интеграций по функционалу и юзабилити.
Об этом и будет данная статья.
Надеемся, что кому-то данный материал покажется интересным и полезным!
С примером настройки можно сразу ознакомиться здесь: Пример создания сценария, запуска процесса и выполнения задач в мессенджерах Max и Telegram.
Введение
В целом подход к интеграции с Telegram и Max ничем не отличаются.
Всё сводится к отправке HTTP-запросов и обработке полученных ответов🙂
Конечно, адреса ресурсов, заголовки и тела запросов будут отличаться, но сами механизмы отправки запросов и обработки ответов одинаковые. За исключением некоторых отдельных нюансов, по-разному реализованных в двух API.
Интеграция с Telegram была в программе реализована достаточно давно - в конце 2020 года. И код этой интеграции уже превратился в своего рода легаси, который лишний раз трогать было не обязательно. Да бОльшая его часть последние несколько лет и не менялась, несмотря на то, что у пользователей некоторые чат-боты, настроенные в рамках нашей системы, имеют до 4000 зарегистрированных пользователей-клиентов.
Для интеграции с Max, если уже есть готовая (и рабочая) интеграция с Telegram, требуется в первую очередь рефакторинг существующего кода. Глубина рефакторинга будет зависеть от того, как весь код был написан изначально.
В нашем случае был модуль нс_Телеграм, процедуры и функции которого реализовывали механизмы интеграции.
Для новой интеграции с Max этот модуль был разделен на 2: нс_ЧатБоты и нс_Телеграм, а также добавлен новый модуль нс_Макс.
Не только отдельные функции и процедуры из одного модуля разъехались по разным модулям, но также и отдельные части некоторых процедур и функций разъехались по разным процедурам и функциям разных модулей.
В общем, такая работа - это отдельный вид удовольствия, который здесь нет смысла описывать.
Остановимся только на некоторых нюансах, которые потребовали отдельного внимания.
Создание и подключение чат-бота
Создание чат-бота в Max отличается от Telegram.
В Telegram это делается в самом мессенджере в специальном боте BotFather и доступно всем.
В Max требуется регистрация на портале Max с подтверждением учетной записи. Например, через Госуслуги.
После этого, в личном кабинете будет доступно создание чат-ботов.
Для целей интеграции для чат-бота генерируется токен, который позволяет отправлять запросы чат-боту и получать от него ответы.
Токен - единственное, что требуется для работы с API Max (как и с API Telegram).
Некоторые отличия в API
В целом, функциональный результат что в Telegram, что в Max получается одинаковый.
Форматированные сообщения с кнопками, возможность отправлять и получать разные виды вложений - это практически, всё, что требуется для организации взаимодействия человека с программой.
Визуально тоже всё очень похоже.
Но некоторые отличия, всё-таки, имеются.
ForceReply
В API Telegram есть объект ForceReply, который принудительно открывает режим ответа пользователю.
Когда пользователю приходит сообщение от чат-бота о необходимости указать какой-то комментарий, текст или вложение, в Telegram-клиенте можно сразу включить режим ответа на конкретное сообщение чат-бота.
В API Max такой возможности нет.
В Max это будет просто сообщение.
Ответ пользователя напрямую не будет связан с запросом от чат-бота.
Поэтому, в случае с Max потребуется дополнительно как-то сохранять "контекст", чтобы после получения ответа чат-бот понимал, что сообщение от пользователя относится именно к его предыдущему запросу.
На скриншотах ниже показано, как будет выглядеть поле ввода сообщения в Max (слева) и в Telegram (справа).
На изображении справа видно, что поле ввода текста/добавления вложений является ответом на запрос чат-бота о заполнении комментария:
"Внутри" это выглядит так:
В данных полученного сообщения Telegram есть поле reply_to_message, в котором есть информация о том, к чему относится полученный текст пользователя.
Программа видит контекст.
В случае с Max мы получаем только сообщение без привязки к сообщению от чат-бота.
Поэтому требуется некоторые дополнительные программный механизмы, чтобы сохранять контекст и иметь возможность корректно обрабатывать полученное сообщение от пользователя.
В целом, конечно, на результат это не влияет.
Пользователь, как правило, должен понимать (и понимает), что сообщение, следующее за запросом о вводе комментария, должно содержать комментарий, а не что-то иное. В противном случае в базу 1С попадет некорректная информация о результатах выполнения очередной задачи.
Отправка вложений
При отправке нескольких вложений из Max в одном сообщении, они приходят с сервера внутри одного сообщения (что и логично).
Для примера, при выполнении задачи отправим вместе с комментарием 2 фотографии:
Чат-бот при обработке сообщения видит, что в сообщении есть 2 файла (поле attachments - массив):
По каждому из вложений массива мы видим id и ссылку для скачивания:
После того, как чат-бот обработает сообщение, в Max будет отправлено сообщение об успешном выполнении задачи:
...а в базе 1С мы увидим 2 файла, который были отправлены исполнителем:
В Telegram, если несколько вложений были отправлены в одном сообщении, каждое вложение придет как отдельное сообщение.
И обрабатывать их будет нужно отдельно.
Поле photo будет содержать массив идентификаторов одного и того же изображения в разных размерах:
Поэтому результат, который увидит пользователь в Telegram будет немного отличаться.
Сначала придет сообщение об успешном выполнении задачи.
А затем придет второе сообщение о том, что в задачу добавлен файл.
Оба файла будут доступны в базе 1С:
В данном примере текст "В задачу добавлен файл" означает, что файл добавляется в уже выполненную задачу.
Этот же механизм позволяет дописывать комментарий в ранее выполненную задачу или добавлять, спустя время, дополнительные вложения:
Например, можно найти в истории сообщений ранее выполненную задачу, нажать у нее кнопку выполнения и добавить комментарий:
Комментарий появится в базе 1С:
Отправка вложений
Чтобы отправить вложение в Telegram достаточно 1 http-запроса.
Код примерно следующего содержания:
АдресЗапроса = "bot" + Токен + "/sendDocument";
ЗапросHTTP = Новый HTTPЗапрос(АдресЗапроса);
ЗапросHTTP.Заголовки.Вставить("Connection", "keep-alive");
ЗапросHTTP.Заголовки.Вставить("Content-Type", "multipart/form-data; boundary=" + Boundary);
ЗапросHTTP.УстановитьТелоИзДвоичныхДанных(ДанныеВложения);
Попытка
ОтветHTTP = Соединение.ОтправитьДляОбработки(ЗапросHTTP)
Исключение
// Обработка ошибки
КонецПопытки;
Чтобы отправить вложение в Max, требуется 3 http-запроса:
- запрос на получение ссылки для загрузки.
- отправка(загрузка) файла по полученной ссылке.
- отправка ссылки получателю сообщения.
По 1-му пункту: запрос будет отличаться в зависимости от типа отправляемого файла.
По 2-му пункту, каких-то нюансов нет: получаем ссылку для загрузки и по ней отправляем файл:
// Хост + АдресРесурса - полученные в 1-ом запросе
Соединение = СоздатьСоединение(Хост, Настройки.Соединение.Таймаут);
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", Токен);
Заголовки.Вставить("Content-Type", "multipart/form-data; boundary=" + Boundary);
ТекущийЗаголовок = СтрШаблон(Заголовок, Вложение.ПолноеИмя);
Тело = Новый ПотокВПамяти;
ЗаписьДанных = Новый ЗаписьДанных(Тело);
ЗаписьДанных.ЗаписатьСтроку(ТекущийЗаголовок);
ЗаписьДанных.Записать(ПолучитьДвоичныеДанныеВложения(Вложение));
ЗаписьДанных.ЗаписатьСтроку(Подвал);
ЗаписьДанных.Закрыть();
ЗапросHTTP = Новый HTTPЗапрос(АдресРесурса, Заголовки);
ЗапросHTTP.УстановитьТелоИзДвоичныхДанных(Тело.ЗакрытьИПолучитьДвоичныеДанные());
Попытка
ОтветHTTP = Соединение.ОтправитьДляОбработки(ЗапросHTTP);
Исключение
КонецПопытки;
3-ий запрос, следует выполнять не сразу, а как написано в документации по API Max: "После загрузки файла сделайте паузу перед отправкой сообщения".
В противном случае можно получить ошибку "{"code":"attachment.not.ready","message":"Key: errors.process.attachment.file.not.processed"}":
Поэтому данный момент следует учитывать при интеграции, чтобы файлы успешно доходили до получателя:
В общем, отправка вложений в Max, по сравнению в Telegram, более сложная.
С одной стороны, конечно, хотелось бы, чтобы всё это оставалось "под капотом" Max и мы могли отправлять вложение 1 запросом, как и в Telegram.
Но с другой стороны, вероятно, разработчики API Max придерживались какой-то оправданной логики.🙂
В остальном, реализация интеграции с Telegram и Max, более-менее похожа🙂
*По-крайней мере в той её части, которую реализовывали мы.
Пример создания сценария, запуска процесса и выполнения задач в мессенджерах Max и Telegram
После настроек попробуем сделать простой сценарий, запустим по нему процесс и выполним задачи, используя оба мессенеджера.
Разветвленный процесс как, например, на изображении ниже нам сейчас не потребуется - сейчас достаточно самого простого примера.
Создадим простой сценарий, в котором сначала надо проверить какое-то условие, по результатам которого процесс пойдет или в одну, или в другую сторону:
В задаче, в которой требуется проверить условие, переименуем стандартные кнопки "Да и "Нет":
В настройках автоматических оповещений добавим для задачи отправку сообщений исполнителю в 2 мессенджера: в Telegram и Max:
Для Max укажем отдельный чат-бот.
*Можно оставить поле пустым. Тогда система будет отправлять сообщения в основной чат-бот, указанный в настройках системы. Но если у нас несколько чат-ботов, мы можем указать какой именно следует использовать.
Процесс запущен.
Исполнителю пришли сообщения в Telegram и Max:
В Telegram мы нажали кнопку "В работу", чтобы в базе 1С у задачи изменился статус.
А в Max выполним задачу, добавив файл:
Комментарий + Файл отправлены в 1С, задача в 1С завершилась и мы получаем подтверждение:
Тексты сообщений, которые приходят в мессенджеры, можно изменить по своему усмотрению в настройках каждого чат-бота:
Задача была успешно выполнена и процесс перешел на следующий шаг.
На карте процесса мы видим текущее состояние процесса и добавленный файл:
На форме следующей задачи исполнитель видит комментарий, который оставил исполнитель по предыдущей задаче, и отправленное вложение:
Эту задачу можно выполнить в базе 1С, но сделаем это в Telegram.
Сначала получим список своих задач.
Затем выберем ту, которую хотим выполнить.
Отметим её выполнение, прикрепив вложение:
Задача успешно завершена, а в базе 1С на карте процесса мы видим, что процесс по нашему сценарию завершился.
Кроме этого, 2-ое вложение также будет доступно для просмотра:
Если присмотреться, то в списке вложений видно, что 1 вложение было сохранено в папку, а 2-ое - как присоединенный файл.
Вариант сохранения вложений настраивается в карточке чат-ботов:
Таким образом, выполнение задач доступно и в Telegram, и в Max. Функционал работы с задачами, при этом, идентичен.
На этом всё!
Надеемся, данная информация окажется для кого-то полезной.
Хорошего дня и успехов в делах! 👍
Вступайте в нашу телеграмм-группу Инфостарт