Gallery

Docs

История изменений

История релизов

НАЧАЛО РАБОТЫ С ПЛАТФОРМОЙ

ПЕРЕД СОЗДАНИЕМ АГЕНТА

КОНСТРУКТОР СЦЕНАРИЯ АГЕНТА

СОЗДАНИЕ АГЕНТА НА ПЛАТФОРМЕ

ОБУЧЕНИЕ И ТЕСТИРОВАНИЕ АГЕНТА

РАЗМЕЩЕНИЕ АГЕНТА В КАНАЛАХ

ЭКСПЛУАТАЦИЯ АГЕНТА

АНАЛИТИКА ОБЩЕНИЯ АГЕНТА

Explore

РАЗМЕЩЕНИЕ АГЕНТА В КАНАЛАХ

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

Chat API — универсальный канал с публичным API, предназначенный для подключения

@Агент⁠

а к

@Конечный канал⁠

ам, для которых нет встроенного в

@Платформа⁠

@Коннектор⁠

Организовать такой универсальный канал можно с помощью

@Коннектор⁠

Подключение

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

⁠

@Агент⁠

у необходимо создать и настроить

@Канал Агента⁠

с коннектором

@Chat API⁠

Войдите в меню редактирования (Edit) настроек вашего

@Агент⁠

⁠

В появившемся окне перейдите на вкладку Channels для настройки каналов, затем:

выберите тип канала

@Omnichannel⁠

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

⁠

⁠

Интеграция с сервером клиента происходит через универсальный

@Коннектор⁠

с названием “Chat API”, установите его в поле Channel.

⁠

По необходимости пропишите заголовок для данного

@Канал Агента⁠

в поле Title.

⁠

После выбора

@Chat API⁠

вам станет доступна ссылка на вебхук канала агента (поле Chatbot webhook: URL).

⁠

⁠

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

где {server_adress} — адрес

@Платформа⁠

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

Установите ваш токен в поле Channel webhook: Token в окне настроек .

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

⁠

Снимок экрана 2023-07-03 в 23.58.55 1.png

⁠

Активируйте канал переключением тумблера для того, чтобы

@Агент⁠

начал отвечать в нем.

⁠

⁠

Если

@Агент⁠

не был обучен, появится предупреждение. В таком случае необходимо обучить

@Агент⁠

а, после чего повторить попытку активации

@Канал Агента⁠

⁠

После активации

@Канал Агента⁠

, если есть проблемы с его доступностью, будет выведено предупреждение (Канал будет активирован несмотря на проблемы):

"Can’t reach channel" — выводится в случае, если сервер не отвечает по указанному URL

⁠

Сохраните

@Канал Агента⁠

— нажмите Save

Все настройки будут применены только после сохранения

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

Поддерживаемый протокол и метод:

HTTPS, POST c content-type JSON

Endpoint для получения запросов каналом агента:

Запросы отправляются на 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 OK

BODY:

{

"result": "ok"

}

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

Канал

@Агент⁠

а неактивен или присутствует ошибка в токене Chatbot 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

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

Ниже изложены форматы, примеры и описания запросов от Публичного 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

Тип запроса: POST

Content-type: application/json

Query-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",

Пример Message:

{

"kind": "attachment",

Подключение

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

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

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

Тип события event

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

Объект Visitor

Объект Message

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

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

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

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

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

Базовый URL

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

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

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

Объект Message

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

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

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

Общение

Маппинг Канальных переменных из Chat API

Возможности общения в канале Chat API

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.