Диалоговый интерфейс к ИТ системам

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

Чат-бот выступает в качестве дополнительного сервиса, расширяющего основную систему, будто то ERP, Ecomm, Helpdesk или другая информационная система (далее просто — система), возможностью вести интерактивные диалоговые коммуникации с пользователями системы в мессенджерах, социальных сетях и онлайн-чате для сайта.

Что дают интеграции для бизнеса:

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

Ниже описаны основные принципы и важные нюансы, на которых строится интеграция основных системы и чат-бота и обмен данными между ними.

Коммуникации в чат-боте

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

Чат-бот — это одновременно как прямой канал связи с пользователями для отправки уведомлений, так и интерактивный интерфейс к системе в виде диалогового приложения, через которое пользователь взаимодействует с системой.

Карты коммуникации 

Для описаний коммуникационных процессов, которые происходят с участием и/или между пользователями систем используется инструмент под названием карта коммуникаций (communication map). Для построения карты коммуникаций вначале согласовываются сущности, с которыми могут происходить изменения: пользователи, заказы, обращения и другие.

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

Пример карты коммуникаций для личного аккаунта пользователя:

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

Приведем пример еще одной карты коммуникаций, в этот раз для реального проекта — чат-бота для Семейного сайта https://fmlst.ru, который выступил мобильным интерфейсом с конструктору семейных веб-сайтов. При желании, можете попробовать чат-бот по адресу: https://t.me/MoyaSemiyaBot. 

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

Примеры из карты коммуникаций для этого проекта выглядят следующим образом:

Точки интеграции

Каждой коммуникации соответствует точка интеграции (integration endpoint). Коммуникации запускаются с помощью вызова нужной точки интеграции, название которой указывается в URL, а в теле запроса в script_request_params указываются параметры коммуникации, например, список ID всех пользователей, которых нужно уведомить. 

Для обеспечения интерактивной коммуникации требуется реализация двусторонней интеграции системы и чат-бота. Команде разработки системы нужен API для вызова массовой и индивидуальной коммуникации с пользователями, а команде разработки чат-бота нужен API для чтения и изменения данных на портале в ходе диалога с пользователем.

Взаимодействия портала и чат-бота происходят по протоколу REST API, а точки взаимодействия, в которых происходит обращение одной системы к ресурсам другой называются точками интеграции (или endpoints). 

У чат-бота есть внутренние точки интеграции (внутренние эндпоинты) для обращения к чат-боту из внешних систем, а также есть внешние точки интеграции (внешние эндпоинты) для обращения к внешним системам из чат-бота. В эндпоинте содержится программный код на JavaScript, в котором пишется код обращения к API, синхронизации данных, запуска коммуникации и прочее.  Подробнее смотрите в разделе Конструктор API.

Ниже показан пример описания точек интеграции для личного аккаунта пользователей:

Метод: POST
URL: {Server URL}/bots/{botId}/call/users/update
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "userId": <ID пользователя в основной системе/required>,
    "lastname": "<Фамилия>",
    "firstname": "<Имя>",
    "patronymic": "<Отчество>",
    "role": "<Роль/required>",
    "active": <Статус активности/bool>,
    "phone": "<Мобильный телефон>",
    "email": "<Email адрес>",
    "location": {
      "country": "<Страна местоположения>",
      "region": "<Регион>",
      "city": "<Город>"
    }
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пользователь не найден"
}

Метод: POST
URL: {Server URL}/bots/{botId}/call/users/connect-bot
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "userId": <ID пользователя в основной системе/required>
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пользователь не найден"
}

Приведем еще несколько примеров:

Метод: POST
URL: {Server URL}/bots/{botId}/call/transaction/thank-you
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "userId": <ID пользователя в основной системе/required>,
    "orderId": <ID заказа/required>
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пользователь не найден"
}

Метод: POST
URL: {Server URL}/bots/{botId}/call/post/new
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "postId": <ID публикации/required>,    
    "authorId": <ID автора публикации/required>,    
    "userIds": [
      <ID первого пользователя/required>,
      <ID второго пользователя>,
      ..
      <ID N-го пользователя>
    ]
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пост не найден"
}

Метод: POST
URL: {Server URL}/bots/{botId}/call/comment/new
Accept: application/json
Content-Type: application/json

{
  "script_request_params": {
    "postId": <ID публикации/required>,    
    "authorId": <ID автора публикации/required>,    
    "commentAuthorId": <ID автора комментария>,
    "comment": "<комментарий>",
    "userIds": [
      <ID первого пользователя/required>,
      <ID второго пользователя>,
      ..
      <ID N-го пользователя>
    ]
  }
}

{
  "success": true
}

{ 
  "success": false,
  "message": "Пост не найден"
}

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

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

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

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

{
  "userId": "<ID пользователя>",
  "email": "<Адрес электронной почты>",
  "phone": "<Телефонный номер>"
}

{
  "userId": 127,
  "surname": "Александр",
  "name": "Сергеевич",
  "patronymic": "Пушкин",
  "role": "user",
  "isActive": true,
  "phone": "79187777777",
  "email": "address@domain.ru",
  "location": {
    "country": "Россия",
    "region": "Ставропольский край",
    "city": "Ставрополь"
  }
}

{
  "firstname": "<Имя>",
  "lastname": "<Фамилия>", 
  "middlename": "<Отчество>",
  "role": "<Роль>",
  "phone": "<Мобильный телефон>",
  "email": "<Email адрес>",
  "location": {
    "country": "<Страна местоположения>",
    "region": "<Регион>",
    "city": "<Город>"
  }
}

{
  "userId": 1177,
}

Синхронизация данных

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

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

Например, если нужно отправить комментарий 50 пользователям о новости, чат-бот подгрузит данные только по новости, сделает рассылку пользователям в чат-боте и на этом все. Когда в системе произойдут новые изменения, система запустит новую коммуникацию и чат-бот снова подтянет нужные данные.

В ходе диалога с чат-ботом пользователи могут внести изменения в системе. Например, получив новость пользователи могут прокомментировать ее. В этому случае, чат-бот вызовет нужные методы API. Основная система зафиксирует изменения в базе данных и затем запустит новую коммуникацию. Цикл повторится.

Подготовка данных для обеспечения коммуникации чат-ботом осуществляется двумя способами:

1. Данные, необходимые для обеспечения коммуникации, подгружаются чат-ботом с помощью API портала по необходимости (pull on demand).
   • Это наиболее часто используемый метод для уведомлений связанных с бизнес-логикой.
   • В этом случае, основная система вызывает нужную коммуникацию, передает ID сущности, ID пользователей (или одного пользователя). Затем чат-бот по ID cущности, подгружает (pull'ит) по API данные необходимые для обеспечения коммуникации.
     
2. Все данные, необходимые для обеспечения коммуникации, целиком и полностью передаются в чат-бот в момент вызова коммуникации порталом (push).
   • Например, можно использовать этот метод используется для синхронизации данных о пользователях. Каждый раз сведения об учетных записях пользователя меняются в основной системе, необходимо их отправлять чат-боту для актуализации. 

Какую архитектуру выбрать зависит от многих факторов, включая от доступных разработчики ресурсов со стороны основной системы и необходимой заказчику гибкости решения и скорости движения. Для максимальной гибкости и скорости движения мы рекомендуем в запросе на коммуникацию передавать базовую информацию, такую как ID ресурса, а для остального запросить у разработчиков основной системы API, чтобы подтягивать данные по мене необходимости. Тогда если вам не хватает каких-то данных, вам не придется просить разработчиков основной системы модифицировать тело запроса — вы подгрузите данные по API. 

Авторизация и регистрация пользователей 

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

После того, как пользователь портала привязал чат-бота к своей учетной записи, а говоря техническим языком, после того, как было установлено однозначное соответствие между идентификатором пользователя в чат-боте (personId/leadId в боте) c идентификатором пользователя в основной системе (userId в системе), можно переходить к коммуникациям. 

Таблица соответствия ID пользователей двух систем хранится в чат-боте. Хранить ID пользователя в чат-боте в БД основной системы нет необходимости.

Для отправки коммуникации системе достаточно сообщить в запросе к чат-боту ID пользователя в системе (userId), которому необходимо отправить коммуникацию. 

Суть интеграции заключается в использовании API для поиска пользователя системы по идентификатору: 

• Чат-бот запрашивает у пользователя ID, имейл или телефон, ищет пользователя в основной системе по API, и если находит, переходит к двухфакторной авторизации через SMS.
• В Telegram можно предложить вариант входа без SMS, сравнивая номер, привязанный к Telegram, с номером, привязанным в основной системе.
• После подтверждения идентификации чат-бот должен сообщить системе, что пользователь привязал чат-бот. Это делается с помощью метода API системы user/connect-bot.
• Метод user/connect-bot устанавливает признак того, что пользователь привязал чат-бот. Теперь система может отправлять сообщения (коммуникации) этому пользователю в чат-бот.

Аналогично работает регистрация через чат-бот:

• Сначала пользователь вводит свои данные, чат-бот ищет пользователя в системе, а если не находит, то создает новую запись с помощью API. 
• Система создает пользователя и возвращает идентификатор нового пользователя (userId).
• Чат-бот выполняет запрос user/connect-bot, чтобы установить у пользователя признак, что чат-бот привязан.
• Теперь канал прямой связи с пользователем установлен и можно вести диалог. 

Возможны и другие варианты интеграции — все зависит от технических возможностей системы и доступных ИТ ресурсов.

Структура API чат-бота

Узнать структуру запроса и проверить работу внутреннего API чат-бота можно с помощью Swagger, доступного по адресу платформы: https://app.metabot24.com/api/docs.

Доступ к Swagger могут получить только авторизованные пользователи, привязанные к проекту. Зарегистрируйтесь на платформе по адресу https://app.metabot24.com, подтвердите электронную почту, авторизуйтесь и затем перейдите по ссылке. 

Внимание! При работе в Swagger платформы будут выполняться реальные API запросы, а не эмуляция API.

Ниже показан пример из Swagger.

Обращение к чат-боту осуществляется через API платформы "POST ​/bots​/{botId}​/call​/{alias}", где:

• В качестве метода используется POST.
• Для идентификатора чат-бота botId на платформе укажите ID вашего бота на платформе, которого предварительно создайте в вашем аккаунте. 
  • ID вы сможете узнать, наведя мышкой на название вашего бота в панели управления.
• Уникальный идентификатор alias точки интеграции (эндпоинта), который соответствует конкретной коммуникации.
  • Узнать название точки интеграции можно воспользовавшись описанием точек интеграции.
• Абсолютно все остальные параметры запроса всегда передаются в тело запроса в массив script_request_params.
  • Остальные параметры, которые по умолчанию выдает Swagger, можете игнорировать.
  • Чтобы узнать точный список параметров запроса, воспользуйтесь таблицами с описанием точек интеграции.
  • Пример body запроса:

  • {
      "script_request_params": {
        "requestId": 100,
        "userId": 1707
      }
    }

В качестве примера рассмотрим ситуацию когда исполнитель принял заявку и необходимо об этом уведомить заказчика. Пример спецификации точки интеграции для этого события показан ниже:     

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

Авторизация запросов API

Адрес сервера API:

https://app.metabot24.com/api/v1 

Для авторизации запросов чат-бота используется Authorization Bearer Token. При каждом вызове API добавляйте заголовок авторизации, пример:

Authorization: Bearer <Access Token>
Accept: application/json
Content-Type: application/json
Access Token предоставляется администратором Metabot.

Обработка ошибок

В случае успеха, чат-бот возвращает код ответа 200 OK, а в теле запроса, содержится информация об успешном выполнении, например:

{ 
  "success": true
}

Если есть ошибка, то также возвращается 200 ОК и дополнительно возвращается текст ошибки в поле message, например:

{ 
  "success": false,
  "message": "Сообщение об ошибке"
}

{ 
  "success": false,
  "errorCode": 422,
  "message": "Ошибка валидации"
}

Все возможные коды ответа сервера:

Подробнее про интеграционные возможности платформы Metabot смотрите в разделе Конструктор API.

Архитектура чат-бота

В РАЗРАБОТКЕ. Обратитесь за шаблоном решения в поддержку.