Универсальный коннектор Chat API

Last updated 1 month ago

Универсальный коннектор Chat API

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

Подключение

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

Агенту необходимо создать и настроить Канал Проекта с коннектором Chat API

Кликните по кнопке настроек Агента.
Нажмите кнопку Add channel.
Откроется панель выбора Конечный канал.
Выберите Chat API.
Откроется панель создания Канал Проекта.
По необходимости пропишите заголовок для данного Канал Проекта в поле названия с плейсхолдером New channel.
Пропишите адрес вашего сервера в поле Channel webhook URL в виде https://{server_adress}, где {server_adress} — адрес Платформа.
Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента: https://your_company.com/send_message.
По необходимости установите токен в поле Channel token.
Важно: токен необходимо указывать в случае, если авторизация на стороне клиента осуществляется через header. Подробнее описано в Авторизация на стороне клиента.
Скопируйте ссылку на вебхук канала агента (поле Chatbot webhook URL), нажав кнопку Copy this webhook.
Для сохранения Канал Проекта без его активации, нажмите кнопку CREATE.
Для сохранения и активации Канал Проекта, нажмите кнопку CREATE & ACTIVATE.
1. Канал Проекта будет сохранен и активирован, если:
2. 1. Агент обучен;
  2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);
  3. будет доступен адрес Канал Проекта;
  4. удастся зарегистрировать вебхук канала.
3. Канал Проекта будет сохранен, но не активирован, если одно или больше условий не будут выполнены.
Для отмены создания Канал Проекта нажмите кнопку CANCEL.

Редактирование и удаление Канала Агента

Чтобы отредактировать значение в любом поле, кликните по полю и впишите новое значение.
1. Изменения будут применены, если:
2. 1. Агент обучен;
  2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);
  3. будет доступен адрес Канал Проекта;
  4. удастся зарегистрировать вебхук канала.
3. Изменения не будут применены, если одно или больше условий не будут выполнены.
1. Изменения будут применены и Канал Проекта будет активирован, если:
2. 1. Агент обучен;
  2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);
  3. будет доступен адрес Канал Проекта;
  4. удастся зарегистрировать вебхук канала.
3. Изменения будут применены, но Канал Проекта не будет активирован, если одно или больше условий не будут выполнены.

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

Поддерживаемый протокол и метод:HTTPS, POST c content-type JSONEndpoint для получения запросов каналом агента:Запросы отправляются на Chatbot Webhook URL, указанный при подключении Канал Проекта.Формат endpoint (Chatbot Webhook URL):

Платформа развернута в облаке

https://admin.chatme.ai/connector/chatapi/chatapi_message/{token}/bot_api_webhook

Платформа развернута в контуре клиента

https://{server_adress}/connector/chatapi/chatapi_message/{token}/bot_api_webhookГде:

{server_adress} — адрес Платформа,
{token} — токен авторизации.

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

Вид тела запроса:

{ "event": (string), "chat_id": (string), "visitor"(optional object): {   "id": (string),   "fields": {     Fields (object)   } }, "message": {   Message (object) }, "service_data"(optional object): {   Service data (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 — объект, содержащий информацию, передаваемую в Агента для обработки.

{  "kind": (string — тип сообщения),  "text": (string — текст сообщения Собеседника),  "data": (JSON — данные о файле или нажатой кнопке)}

Поддерживаемый контент сообщений

Ниже представлены примеры содержимого объекта Message для различных типов сообщений.

Текст

Вид Message:

{"kind": "text","text": (string — message text)}

Пример Message:

{  "kind": "visitor",  "text": "Здравствуйте"}

Файл

Вид Message:

{"kind": "attachment","attachment": { "id": (string — file id), "content_type": (string — Internet Media Type), "url": (string — file URL) }}

Пример Message:

{ "kind": "file_visitor",  "attachment": {    "id": "81f0488",    "content_type": "text",    "size": 560,    "url": "https://yoursite.com/content/file.txt"  }}

При kind == attachment Публичный API "Chat API" получает данные о файле и преобразует их в текстовое сообщение для Агента в формате: file:{file_type}|{file_id}|{file_url} . Сам файл Агент не выкачивает.

Нажатие на кнопку

Вид Message:

{  "kind": "keyboard_response",  "keyboard_response": {    "button": {      "id": (string — идентификатор кнопки),      "text": (string — текст кнопки)    }  }}

Пример Message:

{  "kind": "keyboard_response",  "keyboard_response": {    "button": {      "id": "937bec4863154a2fb0889ff1320d1e2f",      "text": "Задать вопрос оператору"    }  }}

Объект Service data

Service data — любой объект, содержащий кастомную информацию, отправленную в Агента для обработки, например, для использования этой информации в Диалоге. Необязательный объект.

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

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

HTTP status: 200 OKBODY:

{  "result": "ok"}

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

Канал Агента неактивен или присутствует ошибка в токене Chatbot Webhook в URL
HTTP status: 400 Bad RequestBODY:

{    "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

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

Ниже изложены форматы, примеры и описания запросов от Публичного API "Chat API" на сервер клиента.

Базовый URL

Запросы отправляются на URL-адрес клиентского сервера, прописанного в поле Channel Webhook: URL при подключении Канал Проекта.Формат URL-адреса: https://{server_address}/{method}, где:

{server_adress} — адрес Платформа,
{method} — один из методов Публичного API "Chat API".

Методы Публичного API "Chat API":

/send_message — отправка сообщения Агентом Собеседнику.
/close_chat — отправка события для закрытия Диалога.

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

Авторизация может осуществляться через:

Уникальный 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Тип запроса: POSTContent-type: application/jsonQuery-string параметры: не нужныВид URL при отправке Агентом сообщения посетителю:

https://{server_adress}/send_message

где {server_adress} — адрес Платформа.Вид тела запроса:

{    "message": Message (object),    "chat_id": (string)}

Важно: структура объекта Message зависит от типа передаваемого сообщения (текст, файл, кнопки).

Идентификатор chat_id

Объект Message

Message — объект, содержащий информацию, передаваемую в Агента для обработки.

{  "kind": (string — тип сообщения),  "text": (string — текст сообщения Агента),  "data": (JSON — данные о файле),  "buttons": (object — данные о кнопке/кнопках)}

Поддерживаемый контент сообщений

Ниже представлены примеры содержимого объекта Message для различных типов сообщений.

Текст

Вид Message:

{  "kind": "operator",  "text": (string — текст сообщения Агента)}

Пример Message:

{  "kind": "operator",  "text": "Здравствуйте, чем я могу вам помочь?"

Файл

Вид Message:

{ "kind": "attachment", "attachment": {    "url": (string — file URL),    "type": (string — Internet Media Type),    "caption": (string — Attachment Caption. Optional field) }}

Пример Message:

{  "kind": "attachment",  "attachment": {    "url": "https://site.ru/wp-content/uploads/2019/04/diagram.png",    "type": "image/png",    "caption": "подпись"  }}

Важно: отправка файлов происходит из слота .

Сообщение с кнопками

Вид Message:

{  "kind": "keyboard",  "buttons": [    [      {        "text": (string — текст кнопки),        "id": (string — идентификатор кнопки)      }    ]  ]}

Пример Message:

{  "kind": "keyboard",  "buttons": [    [      {        "text": "Перевести на техподдержку",        "id": "fedc60c4dc0d4348b48b524d"      }    ],    [      {        "text": "Перевести на отдел продаж",        "id": "574f2caad88a41a7a2d6b667"      }    ]  ]}

Важно: идентификатор кнопки может содержать только латинские буквы, цифры, символы дефиса и нижнего подчёркивания, и должен быть не более 24 символов в длину.

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

Перевод на оператора не поддерживается с помощью Слота . Для выполнения перевода на оператора используется Внешний запрос с указанными характеристиками.

Важно: Публичный API "Chat API" имеет ограниченный набор возможностей. Если необходимо, чтобы Агент использовал другие методы со стороны API клиента, то работу с этими методами можно настроить внутри Агента при помощи конструктора запросов (Вкладка внешних запросов — External Requests).

Важно: Закрытие Диалога производится с помощью Слота Change Chat Mode. Диалог автоматически закрывается на стороне Платформа.

Запрос для перевода на оператора

Метод: /close_chatТип запроса: POSTContent-type: application/jsonQuery-string параметры: не нужныURL: https://{server_address}/close_chatВид тела запроса: