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

Что такое чат-боты и SmartApp

Знакомство с eXpress

Для избежания проблем при разработке чат-бота или SmartApp необходимо понимание особенностей мессенджера "eXpress".

Структурно "eXpress" представляет собой набор корпоративных (CTS) и региональных (RTS) серверов, объединенных в единую федерацию. Пример представлен на рисунке ниже:

Рисунок_1

Зелёным цветом обозначен сервер RTS, на который пользователь попадает, зарегистрировавшись по номеру телефона. Синим – серверы CTS, на которые можно зайти только с использованием корпоративного аккаунта. CTS-пользователи могут общаться с RTS-пользователями напрямую. Каналы связи для пользователей, зарегистрированных на CTS разных компаний, могут проходить через RTS или могут быть настроены напрямую с помощью доверительных подключений – трастов. Трасты предпочтительно настраивать между несколькими CTS одной компании.

Ниже представлены схемы возможных каналов связи между пользователями разных CTS. Такие схемы называются роутингом и автоматически формируются приложением для каждого чата.

Рисунок_2

Чтобы посмотреть роутинг чата, перейдите в карточку чата и выберите пункт Роутинг.


Чат-бот и SmartApp

Мессенджер "eXpress" предоставляет возможность разработки чат-ботов и SmartApp.


Чат-бот

Рисунок_4

Это отдельный тип пользователя в мессенджере, за которым скрывается веб-приложение (бэкенд). Веб-приложение взаимодействует с пользователем через чат. Чат-боты обладают функционалом, знакомым многим из других мессенджеров:

  • отправка текстовых сообщений, файлов;
  • отправка сообщений с кнопками;
  • получение системных событий (создание чата, вход пользователя в чат и т.д.);
  • включение/отключение режима повышенной конфиденциальности;
  • назначение администраторов чата;
  • создание чата с пользователем (полезно для корпоративных чат-ботов);
  • и т.д.

Подключить чат-бота можно в панели администратора CTS-сервера. Сервер RTS не поддерживает данный функционал.

Процедура управления чат-ботами в панели администратора описана в руководстве администратора (Эксплуатация корпоративного сервера -> Управление контактами -> Чат-боты).


SmartApp

Рисунок_5

Это чат-бот, обладающий собственным фронтендом (SPA-приложение). Фронтенд SmartApp запускается внутри клиентских приложений "eXpress" (Android, Desktop, iOS, Web). SmartApp взаимодействует с клиентским приложением и SmartApp бэкендом через клиентское приложение. Оно также обеспечивает фронтенд SmartApp поддержкой push-уведомлений и хранилищем данных.

Для любого бота можно включить SmartApp в панели администратора.


Платформа BotX

Общие сведения о платформе

BotX – это микросервис, входящий в состав мессенджера для взаимодействия чат-ботов и SmartApp с мессенджером eXpress. Взаимодействие происходит с помощью двух RESTful HTTP API.

Если веб-приложению необходимо выполнить действие от лица аккаунта бота (отправить сообщение, SmartApp событие, создать чат), оно выполняет запрос в BotX API.

Если из мессенджера поступила команда, микросервис BotX отправляет её в веб-приложение (на URL, указанный в панели администратора при создании бота), используя Bot API.

Итог:

  • для выполнения действий от лица бота веб-приложение должно поддерживать работу с BotX API;
  • для обработки команд, поступающих из мессенджера, веб-приложение должно реализовывать Bot API.

Полное описание BotX API, Bot API и их ограничений доступно по ссылке.


Версионирование API

В BotX API каждый метод имеет свою версию.

Например, /api/v3/botx/notification/callback/direct и /api/v4/botx/notifications/direct – это две версии одного и того же метода отправки сообщения.

В Bot API от версии зависят все методы сразу. Микросервис BotX при обращении к чат-боту (или SmartApp) использует версию, указанную при регистрации в панели администратора.

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


Информация о пользователе и роутинг

Рисунок_6

Рассмотрим скриншот роутинга чата с чат-ботом. В данном чате собраны следующие комбинации пользователей:

  • Shepard и чат-бот находятся на одном CTS;
  • esmakotin_5 находится на другом CTS относительно чат-бота, трасты настроены;
  • esmakotin8 находится на другом CTS относительно чат-бота, трасты не настроены;
  • smak rts 14 находится на RTS (является региональным пользователем).

Ниже рассмотрим каждый из вариантов роутинга подробнее.


Вариант 1. Пользователь и чат-бот находятся на одном CTS

Чат-боту доступна вся информация о пользователе. Ниже представлен пример для пользователя Shepard в формате JSON:

{
    "ad_domain": "test.********",
    "ad_login": "********",
    "app_version": "1.25.34",
    "chat_type": "chat",
    "device": "Firefox 95.0",
    "device_meta": {
        "permissions": {
            "microphone": true,
            "notifications": false
        },
        "pushes": false,
        "timezone": "Europe/Moscow"
    },
    "device_software": "Linux",
    "group_chat_id": "********-8c24-005e-0200-f5dedfcb454d",
    "host": "cts1dev.********",
    "is_admin": true,
    "is_creator": true,
    "locale": "en",
    "manufacturer": "Mozilla",
    "platform": "web",
    "platform_package_id": "ru.unlimitedtech.express",
    "user_huid": "********-1be8-55f7-b800-fa15ddee5167",
    "username": "********"
}
Чат-бот может найти пользователя через методы поиска.

Примечание

SmartApp виден только пользователям, зарегистрированным с ним на одном CTS. Для получения информации о разработке SmartApp перейдите к разделу "Аккаунты чат-бота, доступ к чат-боту".


Вариант 2. Пользователь находится на другом CTS

Для остальных трёх случаев (трасты настроены, трасты не настроены, пользователь региональный) чат-боту доступно гораздо меньше информации о пользователе. Пример в формате JSON представлен ниже:

{
    "ad_domain": null,
    "ad_login": null,
    "app_version": null,
    "chat_type": "group_chat",
    "device": null,
    "device_meta": {},
    "device_software": null,
    "group_chat_id": "********-0d51-5f64-8a06-5e8d0455ed4f",
    "host": "cts1dev.********",
    "is_admin": false,
    "is_creator": false,
    "locale": "en",
    "manufacturer": null,
    "platform": null,
    "platform_package_id": null,
    "user_huid": "********-e12d-5efe-a111-51fe01aac911",
    "username": null
}
[Методы поиска] (https://hackmd.ccsteam.ru/s/E9MPeOxjP#Users-API) недоступны.

Примечание

Атрибут host – это хост, на котором находится чат-бот, получивший сообщение.


Аккаунты чат-бота, доступ к чат-боту

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

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


Чат-бот, обрабатывающий только личные сообщения

Пример: чат-бот для оформления отпусков.

Сценарий: Сотрудник пишет чат-боту со своего CTS. Если начальник находится на другом CTS, с ним связывается другой аккаунт чат-бота.

Проверка на пользователя с текущего CTS:

  • На стороне BotX. В панели администратора выполняется настройка communication_availability. Данный подход не требует доработки чат-бота.
  • На стороне чат-бота. Чат-бот проверяет, что пользователь принадлежит текущему CTS (username != null). Преимущество этого способа в том, что чат-бот может отправить пользователю сообщение. Например, предоставить ссылку на правильного чат-бота.


Чат-бот, поддерживающий взаимодействие в групповых чатах

Пример: чат-бот, создающий голосования.

Проблемы: Непонятно, какой из аккаунтов нужно добавить в групповой чат, объединяющий несколько CTS. При выгрузке результатов голосования будут доступны не все имена голосовавших.

Решение: Выделить основной аккаунт чат-бота, который пользователи будут добавлять в чаты. Остальные аккаунты чат-бота, которые существуют для получения данных при выгрузке результатов, скрыть с помощью опции show_in_catalog в панели администратора.


Видимость сообщений в групповых чатах

В групповых чатах видимость сообщений настраивается:

  • чат-бот не видит сообщений (например, если чат-бот должен общаться только в ЛС);

  • чат-бот видит только те сообщения, в которых есть ссылка на него (выбрано по умолчанию);

  • чат-бот видит все сообщения (например, при использовании чат-бота в качестве модератора).

В личных чатах чат-бот видит все сообщения.

Настройка видимости сообщений настраивается свойством allowed_data в панели администратора.


Что означают галочки при отправке сообщений чат-боту

  1. Одна серая галочка – сообщение отправлено.

  2. Две серые галочки – BotX получил сообщение.

  3. Две синие галочки – BotX отправил сообщение чат-боту, а чат-бот ответил на запрос (приступил к обработке или отклонил).


Шифрование трафика между чат-ботом и BotX

По умолчанию трафик между микросервисом BotX и веб-приложением чат-бота не шифруется, т.к. чат-бот и бэкенд eXpress находятся в закрытой сети заказчика. Доступна настройка шифрования с помощью протокола TLS.

Для настройки шифрования:

  1. Подключите сертификат на стороне CTS (загружается корневой сертификат, которым подписаны сертификаты ботов).

  2. Активируйте опцию use_botx_ca_cert в панели администратора.

Подробно операция описана в руководстве администратора (Эксплуатация корпоративного сервера -> Управление контактами -> Чат-боты).

Настройка use_botx_ca_cert позволяет проверять подлинность сертификата. Используется для предотвращения утечки данных, например, при указании злоумышленником стороннего бота для перенаправления трафика.