БиблиотекаMaxBot

БиблиотекаMaxBot — библиотека для 1С:Предприятие.Элемент, которая упрощает интеграцию приложения с чат-ботами MAX. Библиотека берет на себя настройку webhook, прием и разбор входящих событий, отправку сообщений через HTTP API MAX и хранение справочных данных по чатам и участникам.

Возможности

Подключение бота MAX к опубликованному приложению через webhook.
Прием входящих событий по HTTP endpoints приложения.
Маршрутизация входящих событий в прикладную реализацию через сервисный контракт.
Отправка текстовых сообщений в чат.
Ответ на конкретное сообщение.
Редактирование ранее отправленного текстового сообщения.
Отправка файлов, изображений и видео.
Отображение действий бота: набор текста, отправка файла, отправка фото.
Добавление и удаление участников чата.
Удаление одного или нескольких сообщений.
Работа с inline-клавиатурой и callback-кнопками.
Поддержка режимов форматирования HTML и Markdown.
Автоматическое создание и хранение данных по чатам и пользователям MAX.
Журналирование входящих вызовов webhook в режиме отладки.

Что библиотека делает автоматически

Библиотека создает и использует собственные метаданные:

справочник Чаты — хранит идентификатор чата, тип и дату создания;
справочник УчетныеЗаписиМакс — хранит идентификатор пользователя MAX, логин, имя, фамилию и признак бота;
регистр НастройкиПрограммы — хранит токен бота, секрет входящих вызовов, режим работы и отладочные настройки;
историю вызовов webhook — для диагностики интеграции.

При регистрации webhook библиотека настраивает callback на URL приложения вида:

https://<адрес_публикации>/api/max/send

Также доступен endpoint проверки:

https://<адрес_публикации>/api/max/ping

Для защиты входящих вызовов библиотека проверяет заголовок X-Max-Bot-Api-Secret.

Архитектура интеграции

Интеграция строится вокруг трех элементов:

Публикация приложения с доступным извне HTTPS-адресом.
Настройка токена бота и регистрация webhook в MAX.
Реализация контракта ВходящиеСообщения, через который прикладное решение обрабатывает события.

Поддерживаемые входящие события

Библиотека подписывает webhook на несколько типов обновлений MAX, а в прикладной код маршрутизирует следующие события:

message_created — входящее сообщение;
message_callback — нажатие на callback-кнопку;
user_added — добавление участника;
user_removed — выход или удаление участника.

Для них используются структуры:

ВходящееСообщениеМакс;
ЗапросОбратногоВызова;
ИзменениеУчастникаЧата.

Быстрый старт

1. Подключите библиотеку к своему приложению

Добавьте библиотеку в состав решения и опубликуйте приложение по HTTPS так, чтобы адрес был доступен серверу MAX.

2. Создайте бота в MAX

Создайте чат-бота в MAX и получите токен доступа. В интерфейсе библиотеки для этого предусмотрена форма ПодключениеБота, в которой можно:

сохранить токен бота;
зарегистрировать webhook на текущее приложение;
проверить состояние подключения;
отключить webhook.

3. Реализуйте контракт входящих событий

Создайте сервис, реализующий контракт ВходящиеСообщения. Библиотека вызовет его методы при поступлении webhook-событий.

Пример минимальной реализации:

абстрактный метод ОбработатьВходящееТекстовоеСообщение(ВходящееСообщениеМакс: ВходящееСообщениеМакс)

абстрактный метод ОбработатьОбратныйВызов(ЗапросОбратногоВызова: ЗапросОбратногоВызова)

абстрактный метод ОбработатьИзменениеУчастникаЧата(ИзменениеУчастникаЧата: ИзменениеУчастникаЧата)

Пример прикладной логики:

метод ОбработатьВходящееТекстовоеСообщение(ВходящееСообщениеМакс: ВходящееСообщениеМакс)

    если ВходящееСообщениеМакс.ТекстСообщения == "/start"
        Макс.ОтправитьТекстовоеСообщение("Бот подключен и готов к работе", ВходящееСообщениеМакс.Чат)
        возврат
    ;

    знч Ответ = новый ОтветНаСообщение(
        Чат = ВходящееСообщениеМакс.Чат,
        ИдентификаторСообщения = ВходящееСообщениеМакс.ИдентификаторСообщения,
        Текст = "Сообщение получено"
    );

    Макс.ОтветитьНаСообщение(Ответ)

;

метод ОбработатьОбратныйВызов(ЗапросОбратногоВызова: ЗапросОбратногоВызова)
    Макс.ОтправитьТекстовоеСообщение("Нажата кнопка: " + ЗапросОбратногоВызова.Данные, ЗапросОбратногоВызова.Чат)
;

метод ОбработатьИзменениеУчастникаЧата(ИзменениеУчастникаЧата: ИзменениеУчастникаЧата)
;

4. Зарегистрируйте webhook

Webhook можно установить через форму настройки или программно:

Макс.УстановитьВебХук("https://example.org/myapp")

В этом случае библиотека зарегистрирует callback на URL https://example.org/myapp/api/max/send.

5. При необходимости включите отладку

Для отладки можно установить webhook в специальном режиме:

НастройкиМаксКлиент.УстановитьВебХукНаТекущееПриложение("РежимОтладки")

В этом режиме библиотека сохраняет тело входящего webhook и тело ответа в историю вызовов. Это удобно на этапе первичной настройки и диагностики проблем интеграции.

Модель входящих данных

`ВходящееСообщениеМакс`

Содержит основные данные входящего сообщения:

ТекстСообщения;
Автор;
Чат;
ИдентификаторСообщения;
ТипЧата;
Локация;
ИдентификаторОтмеченногоСообщения;
ТекстОтмеченногоСообщения;
ИдентификаторПользователяОтмеченногоСообщения.

`ЗапросОбратногоВызова`

Содержит данные callback-события:

Идентификатор;
Автор;
ИдентификаторСообщения;
ТекстСообщения;
Данные;
Чат;
ТипЧата.

`ИзменениеУчастникаЧата`

Содержит данные по изменению состава участников:

Чат;
Автор;
Участник;
Статус (Добавленный или Покинувший);
ТипЧата.

API исходящих действий

Основные методы, которые предоставляет библиотека:

Сообщения

Макс.ОтправитьТекстовоеСообщение(ИсходящееСообщение)
Макс.ОтправитьТекстовоеСообщение("Текст", Чат)
Макс.ОтветитьНаСообщение(ОтветНаСообщение)
Макс.ОтредактироватьТекстовоеСообщение(РедактируемоеТекстовоеСообщение)
Макс.УдалитьСообщение(ИдентификаторСообщения, Чат)
Макс.УдалитьСообщения(ИдентификаторыСообщений, Чат)

Действия бота

Макс.ОтобразитьДействиеБота(Чат, ДействияБота.НабираетСообщение)
Макс.ОтобразитьДействиеБота(Чат, ДействияБота.ОтправляетФайл)
Макс.ОтобразитьДействиеБота(Чат, ДействияБота.ОтправляетФото)

Работа с участниками

Макс.ДобавитьПользователя(ИдентификаторПользователя, Чат)
Макс.УдалитьПользователя(ИдентификаторПользователя, ИдентификаторАдминистратора, Чат)

Отправка вложений

Макс.ОтправитьФайл(ДвоичныйОбъектСсылка, Медиа.Изображение, Чат, "Подпись")
Макс.ОтправитьФайл(ДвоичныйОбъектСсылка, Медиа.Файл, Чат)
Макс.ОтправитьФайл(ДвоичныйОбъектСсылка, Медиа.Видео, Чат)

Формирование сообщений

Для отправки сообщений используются структуры:

ИсходящееСообщение;
ОтветНаСообщение;
РедактируемоеТекстовоеСообщение;
КлавиатураСообщения;
КнопкаКлавиатурыСообщения.

Поддержка форматирования

Перечисление РежимРазбораТекста поддерживает значения:

ОбычныйТекст;
HTML;
Markdown.

Пример сообщения с inline-клавиатурой

знч Кнопка = новый КнопкаКлавиатурыСообщения(
    Текст = "Подтвердить",
    ДанныеОбратногоВызова = "confirm"
);

знч Клавиатура = новый КлавиатураСообщения(
    Клавиатура = [[Кнопка]]
);

знч Сообщение = новый ИсходящееСообщение(
    Чат = Чат,
    Текст = "Выберите действие",
    ШаблонОтвета = Клавиатура,
    РежимРазбораТекста = РежимРазбораТекста.HTML
);

Макс.ОтправитьТекстовоеСообщение(Сообщение)

Кнопка может содержать:

текст;
URL-ссылку;
payload для callback;
текст для копирования в буфер обмена.

Дополнительные точки расширения

Права доступа

Если требуется встроить библиотечные данные в свою модель безопасности, можно реализовать контракт ПраваДоступаБиблиотекаМакс_КонтрактСервиса. Через него задаются разрешения для:

Чаты;
УчетныеЗаписиМакс;
НастройкиПрограммы;
ИсторияВызововВебХука.

Статистика использования

Для регистрации запуска регламентных заданий предусмотрен контракт СтатистикаИспользованияПриложенияБиблиотекаМакс_КонтрактСервиса.

Требования к интеграции

опубликованное приложение 1С:Элемент с доступным извне HTTPS-адресом;
созданный бот в MAX и действующий токен;
реализация контракта ВходящиеСообщения в прикладном решении;
доступ сервера приложения к HTTP API MAX.

Когда библиотека подходит

Библиотека полезна, если нужно быстро встроить в решение 1С:

бота поддержки или уведомлений;
обработку команд из личных и групповых чатов;
интерактивные сценарии с inline-кнопками;
реакцию на события состава участников чата;
отправку файлов и медиа из прикладного кода.