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

Omnichannel — универсальный канал с публичным API, предназначенный для подключения Агента к Конечным каналам, для которых нет встроенного в Платформу брендового коннектора. Организовать такой универсальный канал можно с помощью Универсального коннектора Omnichannel.

Подключение

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

Для Агента необходимо создать и настроить Канал Агента с коннектором Omnichannel.

  1. В появившемся окне перейдите на вкладку Channels для настройки каналов, далее:

    1. выберите тип канала Omnichannel

  2. Интеграция с сервером клиента происходит через универсальный Коннектор с названием “Omnichannel”, установите его в поле Channel.

    1. Заголовки разных каналов агента могут совпадать.

  3. Пропишите адрес вашего сервера в поле Channel webhook: URL в виде https://{server_adress}, где {server_adress} — адрес Платформы. Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента: https://your_company.com/send_message.

  4. Сохраните Канал Агента — нажмите 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": "ivan@gmail.com",
   "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 символов от Агента до Собеседника

на усмотрение канала

Использование маркдауна

Нет

Last updated