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

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

Подключение

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

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

1. Кликните по кнопке настроек Агента.

2. Нажмите кнопку Add channel.

3. Откроется панель выбора Конечный канал.

4. Выберите Chat API.

5. Откроется панель создания Канал Проекта.

6. По необходимости пропишите заголовок для данного Канал Проекта в поле названия с плейсхолдером New channel.

7. Пропишите адрес вашего сервера в поле Channel webhook URL в виде https://{server_adress}, где {server_adress} — адрес Платформа.

8. Важно: к указанному адресу будет подставлен метод при отправке Агентом ответа на запрос из канала/сервера клиента: https://your_company.com/send_message.

9. По необходимости установите токен в поле Channel token.

10. Важно: токен необходимо указывать в случае, если авторизация на стороне клиента осуществляется через header. Подробнее описано в Авторизация на стороне клиента.

11. Скопируйте ссылку на вебхук канала агента (поле Chatbot webhook URL), нажав кнопку Copy this webhook.

12. 

13. Для сохранения Канал Проекта без его активации, нажмите кнопку CREATE.

14. Для сохранения и активации Канал Проекта, нажмите кнопку CREATE & ACTIVATE.

15. 1. Канал Проекта будет сохранен и активирован, если:

    2. 1. Агент обучен;

       2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

       3. будет доступен адрес Канал Проекта;

       4. удастся зарегистрировать вебхук канала.

    3. Канал Проекта будет сохранен, но не активирован, если одно или больше условий не будут выполнены.

16. Для отмены создания Канал Проекта нажмите кнопку CANCEL.

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

Для редактирования Канал Проекта, необходимо кликнуть по его иконке на карточке Агента.

1. Чтобы отредактировать значение в любом поле, кликните по полю и впишите новое значение.

2. Чтобы применить изменения к активированному Канал Проекта, нажмите кнопку APPLY.
3. 1. Изменения будут применены, если:

   2. 1. Агент обучен;

      2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

      3. будет доступен адрес Канал Проекта;

      4. удастся зарегистрировать вебхук канала.

   3. Изменения не будут применены, если одно или больше условий не будут выполнены.

4. Чтобы деактивировать Канал Проекта, нажмите кнопку DEACTIVATE.
5. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.
6. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.
7. 1. Изменения будут применены и Канал Проекта будет активирован, если:

   2. 1. Агент обучен;

      2. токен в поле Channel token уникален (нет ли активных Канал Проекта того же типа с тем же значением в поле);

      3. будет доступен адрес Канал Проекта;

      4. удастся зарегистрировать вебхук канала.

   3. Изменения будут применены, но Канал Проекта не будет активирован, если одно или больше условий не будут выполнены.

8. Чтобы отменить внесение изменений, нажмите кнопку CANCEL.
9. Чтобы удалить Канал Проекта, нажмите кнопку DELETE.

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

Поддерживаемый протокол и метод: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": "[phone]",    "email": "[e-mail]",    "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

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Вид тела запроса:

{    "chat_id": (string)}

Общение

Взаимодействие с сервером клиента происходит через Публичный API "Chat API" согласно настройкам аккаунта в сервисе клиента.

Переменная	Конечный канал	Переменная в запросе из канала
channel_conversation_id	Chat API	chat.id
channel_visitor_id	Chat API	visitor.id
channel_visitor_firstname	Chat API	visitor.fields.name
channel_visitor_lastname	Chat API	нет
channel_visitor_account	Chat API	visitor.fields.login
channel_visitor_phone	Chat API	visitor.fields.phone
channel_visitor_email	Chat API	visitor.fields.email
channel_visitor_source	Chat API	visitor.fields.site
channel_service_data	Chat API	service_data

Функционал общения	Конечный канал	Доступность в канале	Примечания
channel_chat_id	Chat API	Да	Формат:<client chat_id>|chat_api
Сообщения дойдут до собеседника, если агент напишет первый в существующем чате	Chat API	На усмотрение канала
Кнопки	Chat API	Да	Нажатие на кнопку приходит как текст лейбла кнопки.
Перевод на оператора	Chat API	Нет	Не поддерживается перевод на оператора через слот Change Chat Mode в текущей реализации функционала Платформа. Перевод на оператора можно сделать “вручную” через External Request.
Передача файлов в виде файлов от Агента (Attachment)	Chat API	Нет
Передача файлов в виде ссылок от Агента (Attachment)	Chat API	Да
Получение файла от Собеседника в сценарий	Chat API	Да	Формат: file:Тип файла|ID файла|Ссылка на файл
Доставка сообщений более 1000 символов от Агента до Собеседника	Chat API	На усмотрение канала
Использование маркдауна	Chat API	Нет