Operator API

подсказка

Operator API — REST API для интеграции операторских каналов с Aimylogic.

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

Методы API позволяют:

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

Методы API

При интеграции с Aimylogic по Operator API вы должны создать веб-сервер, который поддерживает запросы:

• POST {apiUrl}/setWebhook
• POST {apiUrl}/sendText
• POST {apiUrl}/sendFile
• POST {apiUrl}/closeChat
• POST {apiUrl}/selectDestination
• GET {apiUrl}/getDestinations

предупреждение

Во всех запросах к Operator API используется {apiUrl} — полный URL-адрес веб-сервера, на который будут отправляться запросы. Иными словами, это URL используемой вами операторской платформы.

POST /setWebhook

Метод устанавливает URL, на который будут направляться события для обработки Aimylogic. Например, отправка сообщения оператором или закрытие чата.

Запрос

POST {apiUrl}/setWebhook

Тело запроса

{
  "url": "http://{host_name}/chatadapter/chatapi/webhook/operatorapi/{apiKey}",
}

Параметры запроса

Параметр	Тип	Описание
apiUrl	string	URL веб-сервера, на который будут направляться запросы Operator API.
url	string	Вебхук, который приходит в результате установки setWebhook. В дальнейшем на него необходимо направлять события в Aimylogic.
ApiKey	string	Идентификатор канала.

POST /sendText

Клиент отправил сообщение в чат с оператором.

Запрос

POST {apiUrl}/sendText

Тело запроса

{
   "userId": "<userId>",
   "text": "текст"
}

Параметры запроса

Параметр	Тип	Обязательный	Описание
userId	string	Да	Идентификатор клиента.
text	string	Да	Текстовое сообщение, отправленное клиентом.

POST /sendFile

Клиент отправил файл в чат с оператором.

Запрос

POST {apiUrl}/sendFile

Тело запроса

{
  "userId": "<userId>",
  "url": "http://someUrl",
  "fileName": "example",
  "size": 1
}

Параметры запроса

Параметр	Тип	Обязательный	Описание
userId	string	Да	Идентификатор клиента.
url	string	Да	Ссылка для скачивания файла.
fileName	string	Нет	Имя файла для скачивания.
size	integer	Нет	Размер файла в байтах.

POST /closeChat

Клиент закрыл чат с оператором.

Запрос

POST {apiUrl}/closeChat

Тело запроса

{
  "userId": "<userId>",
  "text": "Пользователь закрыл диалог"
}

Параметры запроса

Параметр	Тип	Обязательный	Описание
userId	string	Да	Идентификатор клиента.
text	string	Да	Текстовое сообщение, отправленное при закрытии чата.

POST /selectDestination

Метод устанавливает сессию между клиентом чат-бота и выбранным оператором.

Запрос

POST {apiUrl}/selectDestination

Тело запроса

{
   "userId":"<userId>",
   "destinationId":"54321",
   "userName":"firstName lastName",
   "attributes":{
      "key1":"value1",
      "key2":"value2"
   },
   "hiddenAttributes":{
      "key1":"value1",
      "key2":"value2"
   },
   "customData":{

   }
}

Параметры запроса

Параметр	Тип	Обязательный	Описание
userId	string	Да	Идентификатор клиента, присвоенный в Aimylogic.
destinationId	string	Да	Идентификатор оператора, присвоенный приложением оператора.
userName	string	Нет	Имя клиента. Если значение не передано, то оператор увидит {channel} {userId} в качестве имени.
attributes	string	Нет	Пречат поля. Принимает JSON в виде пар {"ключ":"значение"}. Параметры будут переданы оператору как дополнительная информация о клиенте.
hiddenAttributes	string	Нет	Пречат поля, которые не будут переданы оператору. Формат аналогичен attributes.
customData	string	Нет	Дополнительные данные при переводе на оператора.

GET /getDestinations

Получение доступных групп операторов для направления событий.

Запрос

GET {apiUrl}/getDestinations

Ответ

{
   "destinations":[
      {
         "destinationId":"1",
         "name":"Группа операторов 1",
         "hasOnline":true
      },
      {
         "destinationId":"2",
         "name":"Группа операторов 2",
         "hasOnline":false
      }
   ]
}

Формат ответа

Параметр	Тип	Описание
destinationId	string	Идентификатор группы операторов.
name	string	Имя группы операторов.
hasOnline	boolean	Доступность группы операторов для направления событий.

Передача событий в Aimylogic

подсказка

При запросе POST {apiUrl}/setWebhookбудет установлен вебхук, на который следует направлять события от операторов.

Формат вебхука

http://{host_name}/chatadapter/chatapi/webhook/operatorapi/{apiKey}

Запрос

POST ​/chatapi​/webhook​/operatorapi​/{apiKey}

Тело запроса

Тело запроса содержит информацию, необходимую для создания или изменения объекта. Информация должна передаваться в формате JSON.

Ниже представлены допустимые для отправки события, их структура и поля.

Развернуть

Request body: TextMessage | FileMessage | Closed

TextMessage: {
    "id": "id",
    "userId": "54321",
    "type": "TextMessage",
    "text": "text",
    "employee": {
        "employeeId": "id",
        "firstName": "first name",
        "lastName": "last name",
        "avatarUrl": "http://someUrl",
    },
},

FileMessage {
    "id": "id",
    "userId": "54321",
    "type": "FileMessage",
    "url": "http://someUrl",
    "employee": {
        "employeeId": "id",
        "firstName": "first name",
        "lastName": "last name",
        "avatarUrl": "http://someUrl",
    },
    "name": "example",
    "size": "2",
    "comment": "file",
},

Closed {
    "id": "id",
    "userId": "54321",
    "type": "Closed",
    "employee": {
        "employeeId": "id",
        "firstName": "first name",
        "lastName": "last name",
        "avatarUrl": "http://someUrl",
    },
},

SelectDestination {
    "id": "id",
    "userId": "54321",
    "type": "SelectDestination",
    "destination": {
        "destinationId": "id",
        "name": "name",
        "hasOnline": "true",
    },
}

Типы событий

Событие	Описание
TextMessage	Текстовое сообщение от оператора.
FileMessage	Вложенный файл от оператора.
Closed	Закрытие обращения со стороны оператора.
SelectDestination	Выбор направления обращения.

Параметры запроса

Параметр	Тип	Обязательный	Описание
id	string	Да	Идентификатор сообщения.
userId	string	Да	Идентификатор клиента.
type	string	Да	Тип события.
Employee
employeeId	string	Да	Идентификатор оператора.
firstName	string	Да	Имя оператора.
lastName	string	Да	Фамилия оператора.
avatarUrl	string	Да	Ссылка на аватар оператора.
TextMessage
text	string	Да	Текстовое сообщение, отправленное оператором.
FileMessage
url	string	Да	Ссылка для скачивания файла.
name	string	Да	Имя файла для скачивания.
size	integer	Да	Размер файла в байтах.
comment	string	Да	Комментарий к передаваемому файлу.
SelectDestination
destinationId	string	Да	Идентификатор группы операторов.
name	string	Да	Имя группы операторов.
hasOnline	boolean	Да	Доступность группы операторов для направления событий.

Подключение канала

Авторизуйтесь в Aimylogic, перейдите в проект. Нажмите на панели управления Каналы → Перевод на оператора. Выберите канал для подключения Operator API.

Заполните поля:

• Название — укажите название канала.
• API URL — URL, на который будут направляться запросы Operator API.

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

Чтобы добавить группу операторов, нажмите Добавить группу и заполните следующие поля:

• Название канала — укажите произвольное название для добавляемой группы операторов.
• Описание справочника — добавьте текстовое описание для группы операторов.
• Ids — выберите из выпадающего списка идентификатор группы операторов, существующей на стороне операторского канала.

Вы можете добавить несколько групп аналогичным образом.

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

Нажмите Подключить.

Перевод на оператора

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

Так как Aimylogic позволяет одновременно добавлять только один операторский канал, при добавлении блока Перевод на оператора созданный канал Operator API автоматически будет добавлен в блок, а вам будет необходимо только настроить параметры блока.