Публичный асинхронный API "Omnichannel"
Omnichannel — универсальный канал с публичным API, предназначенный для подключения Агента к Конечным каналам, для которых нет встроенного в Платформу брендового коннектора. Организовать такой универсальный канал можно с помощью Универсального коннектора Omnichannel.
Для Агента необходимо создать и настроить Канал Агента с коннектором Omnichannel.
- 1.Войдите в меню редактирования (Edit) настроек вашего Агента.
- 2.В появившемся окне перейдите на вкладку Channels для настройки каналов, далее:
- 1.выберите тип канала Omnichannel
- 2.Нажмите кнопку Add another channel
- 3.Интеграция с сервером клиента происходит через универсальный Коннектор с названием “Omnichannel”, установите его в поле Channel.
- 4.По необходимости пропишите заголовок для данного канала в поле Title.
- 1.Заголовки разных каналов агента могут совпадать.
- 5.После выбора Omnichannel вам станет доступна ссылка на вебхук канала агента (поле
Chatme webhook: URL
). - 6.Пропишите адрес вашего сервера в поле Channel webhook: URL в виде
https://{server_adress}
, где{server_adress}
— адрес Платформы. Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента:https://your_company.com/send_message
. - 7.Установите ваш токен в поле
Channel webhook: Token
в окне настроек Канала Агента. Важно: токен необходимо указывать в случае, если авторизация на стороне клиента осуществляется через header. Подробнее описано в пункте Авторизация на стороне клиента. - 8.Активируйте канал переключением тумблера для того, чтобы Агент начал отвечать в нем.
- 1.Если Агент не был обучен, появится предупреждение. В таком случае необходимо обучить Агента, после чего повторить попытку активации Канала Агента.
- 9.После активации Канала Агента, если есть проблемы с его доступностью, будет выведено предупреждение (Канал будет активирован несмотря на проблемы):
"Can’t reach channel"
— выводится в случае, если сервер не отвечает по указанному URL - 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 — тип события, которое Агент обрабатывает по определенной логике.
Поддерживаемые типы событий:
new_message
— cобытие, которое передается Агенту каналом/сервером клиента и содержит сообщение от Собеседника.
chat_id — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе.
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 — объект, содержащий информацию, передаваемую в Агента для обработки.
{
"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-адрес клиентского сервера, прописанного в поле 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 — идентификатор чата/диалога/собеседника на сервере клиента (в приложении для общения - конечном канале), на основании которого создается Чат с данным Собеседником в Платформе.
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>|omnichann el |
Сообщения дойдут до собеседника, если агент напишет первый в существующем чате | на усмотрение канала | |
Кнопки | Да | Нажатие на кнопку приходит как текст лейбла кнопки. |
Перевод на оператора | Нет | Не поддерживается перевод на оператора через слот Change Chat Mode в текущей реализации функционала Платформа. Перевод на оператора можно сделать “вручную” через External Request. |
Передача файлов в виде файлов от Агента (Attachment_suBXn ) | Нет | |
Передача файлов в виде ссылок от Агента (Attachment_suBXn ) | Да | |
Получение файла от Собеседника в сценарий | Да | Формат: file:Тип файла|ID файла|Ссылка на файл |
Доставка сообщений более 1000 символов от Агента до Собеседника | на усмотрение канала | |
Использование маркдауна | Нет | |