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

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

Чат-бот выступает в качестве дополнительного сервиса, расширяющего основную систему, будто то 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. Основная система зафиксирует изменения в базе данных и затем запустит новую коммуникацию. Цикл повторится.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   4. {
        "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.

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

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