Перейти к содержанию

Backend

В качестве SmartApp backend выступает чат-бот, который реализует Bot API и умеет работать с BotX API. Bot API необходим для получения информации от SmartApp frontend и не содержит элементов авторизации. Взаимодействие между SmartApp frontend и BotX зашифровано. Для работы с BotX API чат-бот должен передавать токен авторизации в каждом запросе.

Примечание

Для создания чат-бота может использоваться любой язык программирования, поддерживающий получение и отправку HTTP-запросов. Для Python3 разработана библиотека pybotx, которая позволяет значительно ускорить создание новых чат-ботов.

Получение токена

Шаг 1. Создайте чат-бота в консоли администратора CTS-сервера.

  1. Перейдите в раздел "Боты":

    Рисунок_1

  2. Нажмите на кнопку Создать бота.

  3. В открывшемся окне заполните поля:

    Рисунок_2

    Название поля Описание
    App ID Уникальный текстовый идентификатор SmartApp
    URL Адрес, где развернут чат-бот
    Имя Название чат-бота. Для SmartApp данное поле заполнять не нужно
    Статус-сообщение Сообщение, которое будет выводиться создании чата с ботом. Для SmartApp данное поле заполнять не нужно
    Аватар Аватар чат-бота. Для SmartApp загружать аватар не нужно
    Версия протокола Версия протокола, которую будет использовать BotX при обращении к чат-боту. По умолчанию выбрана самая последняя

  4. Нажмите Сохранить.

    Созданный чат-бот отобразится в разделе "Боты".

Шаг 2. Создайте подпись.

  1. В разделе "Боты" консоли администратора CTS-сервера нажмите пиктограма в строке созданного чат-бота.

  2. В открывшемся окне скопируйте ID и secret key.

  3. Создайте подпись, используя скопированные ID и secret key:

    echo "bot_id secret_key" | python3 -c "import base64, hmac, hashlib; bot_id, secret_key = input().split(); signed_bot_id = hmac.new(key=secret_key.encode(), msg=bot_id.encode(), digestmod=hashlib.sha256).digest(); print(base64.b16encode(signed_bot_id).decode())"

Шаг 3. Получите токен.

Для получения токена вызовите соответствующий метод в BotX API с полученной подписью.

Время действия полученного токена не ограничено.

Взаимодействие SmartApp frontend и backend

Для взаимодействия frontend и backend (чат-бота) используется JSONRPC-подобный протокол SmartApp RPC. Взаимодействие асинхронно:

  1. Чат-бот получает системное событие system:smartapp_event, содержащее ID запроса (ref) методом POST на роут /command.
  2. Чат-бот подтверждает его обработку.
  3. Чат-бот формирует ответ и отправляет событие с тем же ref методом POST на роут /notification/callback.
  4. SmartApp frontend получает и обрабатывает сообщение.

Пример отправки события:

Внимание!

В поле data можно передать произвольный JSON-объект, но размер запроса в BotX не должен превышать 1M!

POST https://{express-server}/api/v3/botx/smartapps/event

{
  "ref": "6c4e232e-ce47-4141-9502-998bc0062523",
  "data": {"foo": "bar"},
  "group_chat_id": "8e81b23d-9d01-0934-0d99-9410d621353b",
  "opts": {},
  "smartapp_api_version": 1,
  "smartapp_id": "0d7a43fa-6c4a-5842-b0ab-5e051921e18c"
}
Пример отправки push-уведомления:

POST https://{express-server}/api/v3/botx/smartapps/notification

{
    "body": "Test",
    "group_chat_id": "dec60c05-77b7-0d78-159e-b4fbee4d48f6",
    "opts": {},
    "smartapp_api_version": 1,
    "smartapp_counter": 1
}
Ознакомиться с методом "Отправка smartapp нотификации" вы можете тут в документации.

Получение статики SmartApp frontend

Статика хранится в SmartApp backend и выдается по запросу BotX по роутингу /smartapp_files/static/<path_to_file>.

Передача файлов

Чат-бот принимает и отправляет метаданные файлов вместо самих файлов. После получения команды с метаданными файла чат-бот вызывает метод "Скачивание файла" для файла загрузки в файловую систему. Для отправки файла в SmartApp frontend, его необходимо предварительно загрузить методом "Загрузка файла" и отправить полученные метаданные в событии.

Аутентификация в интегрируемых сервисах

Чат-бот может быть самостоятельной информационной системой, но чаще выступает посредником для передачи информации между SmartApp frontend и интегрируемой системой. На схеме ниже представлена последовательность передачи запроса от SmartApp frontend в целевую систему:

Рисунок_1

Возможны два варианта авторизации в интегрируемой системе:

  • сервисная учетная запись, которая позволяет выполнять действия для любого пользователя;
  • single Sign On (SSO), построенный на базе Keyсloak.

SSO позволяет использовать пользовательскую авторизацию для доступа к интегрируемым ресурсам. В схеме SSO применяется Keycloak в качестве IDP для всех систем.

На схеме ниже показано, как запрос от SmartApp frontend обогащается токеном доступа (access token) пользователя. Это позволяет чат-боту использовать его для аутентификации в интегрируемой системе. Обновление токена осуществляется автоматически:

Рисунок_2

Примечание

Токен доступа передается в заголовке OPEN_ID_ACCESS_TOKEN запроса от CTS к чат-боту. Данный заголовок будет передаваться, если в консоли администратора в настройках чат-бота включить опцию "Использовать OpenID токен для аутентификации бота":

Рисунок_3