Публичный асинхронный API "Omnichannel"
Omnichannel — универсальный канал с публичным API, предназначенный для подключения Агента к Конечным каналам, для которых нет встроенного в Платформу брендового коннектора. Организовать такой универсальный канал можно с помощью Универсального коннектора Omnichannel.
Подключение
Конфигурация канала агента в Платформе
Для Агента необходимо создать и настроить Канал Агента с коннектором Omnichannel.
В появившемся окне перейдите на вкладку Channels для настройки каналов, далее:
выберите тип канала Omnichannel
Интеграция с сервером клиента происходит через универсальный Коннектор с названием “Omnichannel”, установите его в поле Channel.
Заголовки разных каналов агента могут совпадать.
Пропишите адрес вашего сервера в поле Channel webhook: URL в виде
https://{server_adress}
, где{server_adress}
— адрес Платформы. Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента:https://your_company.com/send_message
.Сохраните Канал Агента — нажмите 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}
— токен авторизации.
Общая структура запроса
Вид тела запроса:
Важно: структура объекта Message зависит от типа передаваемого сообщения (текст, файл, нажатие на кнопку) и может состоять из разных видов данных и полей.
Тип события event
event — тип события, которое Агент обрабатывает по определенной логике.
Поддерживаемые типы событий:
new_message
— cобытие, которое передается Агенту каналом/сервером клиента и содержит сообщение от Собеседника.
Идентификатор chat_id
chat_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе.
Объект Visitor
Visitor — объект, содержащий информацию о Собеседнике.
Вид Visitor:
Пример Visitor:
Объект Message
Message — объект, содержащий информацию, передаваемую в Агента для обработки.
Поддерживаемый контент сообщений
Ниже представлены примеры содержимого объекта Message для различных типов сообщений.
Текст
Вид Message:
Файл
Вид Message:
Важно: событие будет обработано только при получении state == ready
.
При kind == file_visitor
Публичный API "Omnichannel" получает данные о файле и преобразует их в текстовое сообщение для Агента в формате: file:{file_type}|{file_id}|{file_url}
. Сам файл Агент не выкачивает.
Нажатие на кнопку
Вид Message:
Ответы на запросы из канала/сервера клиента к Агенту на Платформе
Ответ Платформы при успешном запросе
HTTP status: 200 OKBODY:
Ответ Платформы при неуспешном запросе
Канал Агента неактивен или присутствует ошибка в токене Chatme Webhook в URL
HTTP status:
400 Bad Request
BODY:
Отсутствует обязательный параметр в теле запроса
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 зависит от типа передаваемого сообщения (текст, файл, кнопки).
Идентификатор chat_id
chat_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе.
Объект Message
Message — объект, содержащий информацию, передаваемую в Агента для обработки.
Поддерживаемый контент сообщений
Ниже представлены примеры содержимого объекта Message для различных типов сообщений.
Текст
Вид Message:
Пример Message:
Файл
Вид Message:
Пример Message:
Важно: отправка файлов происходит из слота Attachment.
Сообщение с кнопками
Вид Message:
Пример Message:
Важно: идентификатор кнопки может содержать только латинские буквы, цифры, символы дефиса и нижнего подчёркивания, и должен быть не более 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 | Да | Формат: |
Сообщения дойдут до собеседника, если агент напишет первый в существующем чате | на усмотрение канала | |
Кнопки | Да | Нажатие на кнопку приходит как текст лейбла кнопки. |
Перевод на оператора | Нет | Не поддерживается перевод на оператора через слот Change Chat Mode в текущей реализации функционала Платформа. Перевод на оператора можно сделать “вручную” через External Request. |
Передача файлов в виде файлов от Агента (Attachment_suBXn ) | Нет | |
Передача файлов в виде ссылок от Агента (Attachment_suBXn ) | Да | |
Получение файла от Собеседника в сценарий | Да | Формат: |
Доставка сообщений более 1000 символов от Агента до Собеседника | на усмотрение канала | |
Использование маркдауна | Нет |
Last updated