Универсальный коннектор 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

    1. Изменения будут применены, если:

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

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

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

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

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

  4. Чтобы деактивировать Канал Проекта, нажмите кнопку DEACTIVATE.

  5. Чтобы применить изменения к деактивированному Канал Проекта, нажмите кнопку SAVE.

  6. Чтобы применить изменения и активировать Канал Проекта, нажмите кнопку SAVE & ACTIVATE.

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

      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": "+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

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

Нет

PreviousOmnideskNextWidget

Last updated