Публичный асинхронный API "Omnichannel"

Omnichannel — универсальный канал с публичным API, предназначенный для подключения Агента к Конечным каналам, для которых нет встроенного в Платформу брендового коннектора. Организовать такой универсальный канал можно с помощью Универсального коннектора Omnichannel.
Подключение
Конфигурация канала агента в Платформе
Для Агента необходимо создать и настроить Канал Агента с коннектором Omnichannel.
1.Войдите в меню редактирования (Edit) настроек вашего Агента.
​
2.В появившемся окне перейдите на вкладку Channels для настройки каналов, далее:
1.выберите тип канала Omnichannel
2.Нажмите кнопку Add another channel
​
3.Интеграция с сервером клиента происходит через универсальный Коннектор  с названием “Omnichannel”, установите его в поле Channel.

​
4.После выбора Omnichannel вам станет доступна ссылка на вебхук канала агента (поле Chatme webhook: URL).
​
5.Пропишите адрес вашего сервера в поле Channel webhook: URL в виде https://{server_adress}, где {server_adress} — адрес Платформы.
Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента: https://your_company.com/send_message.
6.Установите ваш токен в поле Channel webhook: Token в окне настроек Канала Агента.
Важно: токен необходимо указывать в случае, если авторизация на стороне клиента осуществляется через header. Подробнее описано в пункте Авторизация на стороне клиента.
​
7.Активируйте канал переключением тумблера для того, чтобы Агент начал отвечать в нем.
​
1.Если Агент не был обучен, появится предупреждение. В таком случае необходимо обучить Агента, после чего повторить попытку активации Канала Агента.
​
8.После активации Канала Агента, если есть проблемы с его доступностью, будет выведено предупреждение (Канал будет активирован несмотря на проблемы):"Can’t reach channel" — выводится в случае, если сервер не отвечает по указанному URL
​
9.Сохраните Канал Агента — нажмите Save.
Запросы из канала/сервера клиента к Агенту на Платформе
Поддерживаемый протокол и метод:
HTTPS, POST c content-type JSON
Endpoint для получения запросов каналом агента:
Запросы отправляются на Chatme Webhook URL, указанный при подключении Канала Агента.
Формат endpoint (Chatme Webhook URL):
Платформа развернута в облаке
https://admin.chatme.ai/connector/omnichannel/omnichannel_message/{token}/bot_api_webhook
Платформа развернута в контуре клиента
https://{server_adress}/connector/omnichannel/omnichannel_message/{token}/bot_api_webhook
Где:
{server_adress} — адрес Платформы,
{token} — токен авторизации.
Общая структура запроса
Вид тела запроса:
{
  "event": (string),
  "chat_id": (integer),
  "visitor": {
    "id": (string),
    "fields": {
      Fields (object)
    }
  },
  "message": { 
    Message (object)
  }
 }
Важно: структура объекта Message зависит от типа передаваемого сообщения (текст, файл, нажатие на кнопку) и может состоять из разных видов данных и полей.
Тип события event
event — тип события, которое Агент обрабатывает по определенной логике.
Поддерживаемые типы событий:
new_message — cобытие, которое передается Агенту каналом/сервером клиента и содержит сообщение от Собеседника.
Идентификатор chat_id
chat_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе.
Объект Visitor
Visitor — объект, содержащий информацию о Собеседнике.
Вид Visitor:
{
  "id": (string — псевдоуникальный идентификатор Собеседника, назначенный сервером клиента),
  "fields": {
   "name": (string),
   "login": (string),
   "phone": (string),
   "email": (string),
   "site": (string)
   }
  }
Пример Visitor:
{
  "id": "03e1c040d8214bfa8ccfbb053186a24a",
  "fields": {
   "name": "Иван",
   "login": "ivan",
   "phone": "+79991111111",
   "email": "[email protected]",
   "site": "https://site.com"
   }
  }
Объект Message
Message — объект, содержащий информацию, передаваемую в Агента для обработки.
{
"id": (string — идентификатор сообщения на стороне сервера клиента),
"kind": (string — тип сообщения),
"text": (string — текст сообщения Собеседника),
"data": (JSON — данные о файле или нажатой кнопке
}
Поддерживаемый контент сообщений
Ниже представлены примеры содержимого объекта Message для различных типов сообщений.
Текст
Вид Message:
{
"id": (string),
"kind": "visitor",
"text": (string — текст сообщения Собеседника)
}
Файл
Вид Message:
​
{
 "id": (string),
 "kind": "file_visitor",
 "data": {
  "id": (string — идентификатор файла),
  "state": (string — состояние отправки файла),
  "name": (string — имя файла с расширением),
  "content_type": (string — Internet Media Type),
  "size": (integer — размер файла в байтах),
  "url": (string — URL-адрес файла)
  }
 }
Важно: событие будет обработано только при получении state == ready.
При kind == file_visitor Публичный API "Omnichannel" получает данные о файле и преобразует их в текстовое сообщение для Агента в формате: file:{file_type}|{file_id}|{file_url} . Сам файл Агент не выкачивает.
Нажатие на кнопку
Вид Message:
{
  "id": (string),
  "kind": "keyboard_response",
   "data": {
     "button": {
      "id": (string — идентификатор кнопки),
      "text": (string — текст кнопки)
     }
   }
 }
Ответы на запросы из канала/сервера клиента к Агенту на Платформе
Ответ Платформы при успешном запросе
HTTP status: 200 OKBODY:
{
 "result": "ok"
}
Ответ Платформы при неуспешном запросе
Канал Агента неактивен или присутствует ошибка в токене Chatme Webhook в URL
HTTP status: 400 Bad Request
BODY:
{
    "error": "There is no active channel for received event."
}
Отсутствует обязательный параметр в теле запроса
HTTP status: 400 Bad Request
Указан некорректный URL
HTTP status: 404: Not Found
Некорректный JSON тела запроса: невалидный параметр event или kind
HTTP status: 200 OK
Некорректный JSON тела запроса: другие ошибки помимо указания невалидных параметров event или kind
HTTP status: 500 Internal Server Error
Внутренние ошибки сервера
HTTP status: 500 Internal Server Error
Запросы от Платформы в канал/сервер клиента
Ниже изложены форматы, примеры и описания запросов от Публичного API "Omnichannel" на сервер клиента.
Базовый URL
Запросы отправляются на URL-адрес клиентского сервера, прописанного в поле Channel Webhook: URL при подключении Канала Агента.
Формат URL-адреса: https://{server_address}/{method}, где:
{server_adress} — адрес Платформа,
{method} — один из методов Публичного API "Omnichannel".
Методы Публичного API "Omnichannel":
/send_message — отправка сообщения Агентом Собеседнику.
Авторизация на стороне клиента
Авторизация может осуществляться через:
Уникальный URL
Нужно указать URL, содержащий токен, в поле Channel webhook: URL при подключении Канал Агента. При этом поле Channel webhook: Token заполнять не нужно.
Header
Нужно указать токен авторизации в поле Channel webhook: Token при подключении Канала Агента. Токен из поля Channel webhook: Token по умолчанию будет подставлен в header.
Формат авторизации с помощью токена:
Authorization: Token {token}
Пример авторизации:
Authorization: Token ac650a3c369a4b9599ad52ab71943712
Общая структура запроса
Method: /send_message
Тип запроса: POST
Content-type: application/json
Query-string параметры: не нужны
Вид URL при отправке Агентом сообщения посетителю:
https://{server_adress}/send_message
где {server_adress} — адрес Платформы.
Вид тела запроса:
{
     "message": Message (object),
     "chat_id": (integer)
 }
Важно: структура объекта Message зависит от типа передаваемого сообщения (текст, файл, кнопки).
Идентификатор chat_id
chat_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе.
Объект Message
Message — объект, содержащий информацию, передаваемую в Агента для обработки.
{
  "kind": (string — тип сообщения),
  "text": (string — текст сообщения Агента),
  "data": (JSON — данные о файле),
  "buttons": (object — данные о кнопке/кнопках)
  }
Поддерживаемый контент сообщений
Ниже представлены примеры содержимого объекта Message для различных типов сообщений.
Текст
Вид Message:
{
  "kind": "operator",
  "text": (string — текст сообщения Агента)
}
Пример Message:
{
  "kind": "operator",
  "text": "Здравствуйте, чем я могу вам помочь?"
}
Файл
Вид Message:
{
  "kind": "file_operator",
  "data": {
     "url": (string — URL-адрес файла),
     "name": (string — имя файла с расширением),
     "media_type": (string — Internet Media Type)
  }
 }

Пример Message:
{
  "kind": "file_operator",
  "data": {
     "url": "https://site.ru/wp-content/uploads/2019/04/diagram.png",
     "name": "diagram.png",
     "media_type": "image/png"
  }
 }
Важно: отправка файлов происходит из слота Attachment.
Сообщение с кнопками
Вид Message:
{
  "kind": "keyboard",
   "buttons": [
      [
        {
            "text": (string — текст кнопки),
            "id": (string — идентификатор кнопки)
        }
      ]
   ]
}

Пример Message:
{
  "kind": "keyboard",
   "buttons": [
      [
        {
          "text": "Перевести на техподдержку",
          "id": "fedc60c4dc0d4348b48b524d"
        }
      ],
      [
      {
        "text": "Перевести на отдел продаж",
        "id": "574f2caad88a41a7a2d6b667"
      }
    ]
   ]
}
Важно: идентификатор кнопки может содержать только латинские буквы, цифры, символы дефиса и нижнего подчёркивания, и должен быть не более 24 символов в длину.
Перевод на оператора
Перевод на оператора с помощью Слота Change Chat Mode не поддерживается в текущей реализации функционала Платформы. 
Предлагается выполнять перевод на оператора с помощью External Request, используя соответствующий метод клиента.
Важно: Публичный API "Omnichannel" имеет ограниченный набор возможностей. Если необходимо, чтобы Агент использовал другие методы со стороны API клиента, то работу с этими методами можно настроить внутри Агента при помощи конструктора запросов (External Request).
Общение
Взаимодействие с сервером клиента происходит через Публичный API "Omnichannel" согласно настройкам аккаунта в сервисе клиента.
Канальная переменная
Переменная в теле входящего запроса из канала
channel_conversation_id
chat.id
channel_visitor_id
visitor.id
channel_visitor_firstname
visitor.fields.name
channel_visitor_lastname
нет
channel_visitor_account
visitor.fields.login
channel_visitor_phone
visitor.fields.phone
channel_visitor_email
visitor.fields.email
channel_visitor_source
visitor.fields.site
Функционал
Наличие в канале
Описание
channel_chat_id
Да
Формат:<client chat_id>|omnichannel
Сообщения дойдут до собеседника, если агент напишет первый в существующем чате
на усмотрение канала
​
Кнопки
Да
Нажатие на кнопку приходит как текст лейбла кнопки.
Перевод на оператора
Нет
Не поддерживается перевод на оператора через слот Change Chat Mode  в текущей реализации функционала Платформа. Перевод на оператора можно сделать “вручную” через External Request.
Передача файлов в виде файлов от Агента (Attachment_suBXn )
Нет
​
Передача файлов в виде ссылок от Агента (Attachment_suBXn )
Да
​
Получение файла от Собеседника в сценарий
Да
Формат: file:Тип файла|ID файла|Ссылка на файл
Доставка сообщений более 1000 символов от Агента до Собеседника
на усмотрение канала
​
Использование маркдауна
Нет
​

Асинхронный Webim 2.0

Next - Размещение агента в каналах

Поддержка разметки Markdown в Конечных каналах Агента

Last modified 2mo ago

Copy link

On this page

Подключение

Конфигурация канала агента в Платформе

Запросы из канала/сервера клиента к Агенту на Платформе

Общая структура запроса

Ответы на запросы из канала/сервера клиента к Агенту на Платформе

Ответ Платформы при успешном запросе

Ответ Платформы при неуспешном запросе

Запросы от Платформы в канал/сервер клиента

Базовый URL

Авторизация на стороне клиента

Общая структура запроса

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

Общение