chatme.ai
Search
⌃K

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

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

Подключение

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

Для Агента необходимо создать и настроить Канал Агента с коннектором Omnichannel.
  1. 1.
    Войдите в меню редактирования (Edit) настроек вашего Агента.
    ​
  2. 2.
    В появившемся окне перейдите на вкладку Channels для настройки каналов, далее:
    1. 1.
      выберите тип канала Omnichannel
    2. 2.
      Нажмите кнопку Add another channel
      omnichannel.png
      ​
  3. 3.
    Интеграция с сервером клиента происходит через универсальный Коннектор с названием “Omnichannel”, установите его в поле Channel.
    ​
  4. 4.
    По необходимости пропишите заголовок для данного канала в поле Title.
    ​
    1. 1.
      Заголовки разных каналов агента могут совпадать.
  5. 5.
    После выбора Omnichannel вам станет доступна ссылка на вебхук канала агента (поле Chatme webhook: URL).
    image.png
    ​
  6. 6.
    Пропишите адрес вашего сервера в поле Channel webhook: URL в виде https://{server_adress}, где {server_adress} — адрес Платформы. Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента: https://your_company.com/send_message.
  7. 7.
    Установите ваш токен в поле Channel webhook: Token в окне настроек Канала Агента. Важно: токен необходимо указывать в случае, если авторизация на стороне клиента осуществляется через header. Подробнее описано в пункте Авторизация на стороне клиента.
    image.png
    ​
  8. 8.
    Активируйте канал переключением тумблера для того, чтобы Агент начал отвечать в нем.
    тумблер.png
    ​
    1. 1.
      Если Агент не был обучен, появится предупреждение. В таком случае необходимо обучить Агента, после чего повторить попытку активации Канала Агента.
      image.png
      ​
  9. 9.
    После активации Канала Агента, если есть проблемы с его доступностью, будет выведено предупреждение (Канал будет активирован несмотря на проблемы):"Can’t reach channel" — выводится в случае, если сервер не отвечает по указанному URL
    image.png
    ​
  10. 10.
    Сохраните Канал Агента — нажмите 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 символов от Агента до Собеседника
на усмотрение канала
​
Использование маркдауна
Нет
​
Previous
Асинхронный Webim 2.0
Next - Размещение агента в каналах
Поддержка разметки Markdown в Конечных каналах Агента
Last modified 4mo ago