- Онлайн-консультант Webim
- -
- База знаний
- -
- Боты
- -
- Подключение внешних роботов через External Bot API
- -
- External Bot API 1.0
-
-
-
- 01. Обнаружение нового посетителя, ожидающего ответа
- 02. Выбор посетителя сайта из списка и начало диалога
- 03. Набор ответа посетителю, выбор шаблона
- 04. Запрос контактной информации у посетителя
- 05. Отправка файла посетителю
- 06. Кобраузинг
- 07. «Телепортация» пользователей
- 08. Переадресация диалога другому оператору
- 09. Отправка переписки на адрес электронной почты оператора
- 10. Назначение категории посетителю
- 11. Блокировка посетителя
- 12. Вставка гиперссылки в сообщение
- 13. Добавление заметок
- 14. Проверка орфографии
- Agent`s Handbook
- Как включить оповещения в Google Chrome
- Очереди в РМО
- Работа с офлайн-обращениями на РМО
-
- Алгоритмы назначения чатов
- Видимость диалогов
- Вход в систему
- Генератор лидов и автоприглашения
- График работы
- Добавление кнопки Webim в E-mail
- Закрытие диалогов
- Логотип компании в заголовке чата
- Мониторинг активности сотрудников
- Настройка языков
- Общие настройки организации
- Отделы
- Оценки
- Размещения и настройки кнопки на сайте
- Рассылки
- Регистрация операторов и назначение супервизоров
- Системные сообщения
- Список тайм-аутов
- Финансы
- Функции в каналах общения
- Шаблоны ответов
-
- Встраивание административного интерфейса через iframe
- Как узнать версию своего браузера
- Необходимые доступы на сервер
- Необходимые доступы с сервера
- Обработка файлов, загружаемых в чат
- Рекомендации по настройке мониторинга
- Сетевые конфигурации сервиса Webim
- Системные требования Webim для веб-приложения операторов
- Системные требования Webim для посетителя
- Схемы сетевого размещения серверных компонентов
-
-
-
- Webim Mobile SDK 3.0 для интеграции в мобильные приложения iOS
- Webim Mobile SDK 3.0 для интеграции в мобильные приложения Windows Phone 8.1
- Информация о выпусках (Release notes) – Webim Mobile SDK 3 для Android
- Информация о выпусках (Release notes) – Webim Mobile SDK 3 для iOS
- Справочник по Webim Mobile SDK – SDK для интеграции в мобильные приложения iOS (iPhone/iPad)
- Справочник по Webim Mobile SDK для интеграции в мобильные приложения Android
- Push-уведомления
- Webim Cordova Plugin
-
- Webim CRM postMessage Interface
- Webim Custom Channel API
- Как сделать ссылку кнопкой старта чата
- Маршрутизатор чатов
- Обработчики событий чата
- Процедура установки чата Webim на сайт в iframe
-
External Bot API 1.0
Описание
External Bot API 1.0 — это механизм подключения роботов к сервису Webim. Программно-аппаратная часть (бэкенд) таких роботов находится на внешнем относительно сервиса Webim сервере. Общение между сервисом и аппаратно-вычислительной частью происходит через HTTP-запросы из сервиса Webim на этот сервер.
Робот External Bot API принимает от пользователя вопрос и отправляет его на внешний сервер. Сервер генерирует ответ и присылает его обратно в сервис Webim, сервис показывает ответ пользователю. После этого робот снова ожидает вопрос от пользователя.
Если программно-аппаратная часть (бэкенд) робота перестала отвечать, не знает ответа или возникли другие проблемы, то чат переходит в общую очередь.
External Bot API 1.0 является синхронным. Сервис ожидает ответ от робота в теле response
.
В версии Webim 10.0 робот получил название «умный бот». Теперь для создания робота существует специальный интерфейс.
Общая логика
На робота External Bot API автоматически назначаются все онлайн-чаты, которые поступают в отдел, в который этот робот добавлен.
Онлайн-статус робота влияет на общий онлайн-статус системы:
- если робот — «онлайн», то он будет принимать все чаты от пользователей, и кнопка на сайте будет «онлайн»;
- если робот — «невидимка» и нет операторов онлайн, то он будет принимать все чаты от пользователей, но кнопка на сайте будет показываться «офлайн»;
- если робот — «офлайн», то он не будет принимать никакие чаты (и не будет влиять на онлайн-статус кнопки).
Настройка
Инструкция по настройке и подключению умного бота актуальна для сервиса Webim версии 10.0.
Для подключения внешнего робота к сервису Webim:
- Создайте оператора в системе через интерфейс. Инструкцию по созданию оператора см. здесь.
- Перейдите в настройки Вашего аккаунта, выберите раздел Боты.
- В открывшемся окне нажмите на кнопку Создать нового бота.
- Заполните информацию о вашем боте, в поле Ссылка на внешний API впишите URL-адрес внешнего сервера робота.
- Сохраните изменения.
Логика работы робота
Когда в системе происходят различные события, то логика робота-оператора в Webim делает POST-запрос в предоставленный сторонний API-endpoint разработчиков робота. Данные передаются в формате JSON.
При возникновении какой-либо ошибки запроса к API (ответ отличается от ожидаемого или запрос закрылся по таймауту (5 сек)) чат автоматически переводится в общую очередь операторов. Робот имеет два события: new_chat, new_message.
Текущие поддерживаемые события:
В версии API 1.0 HTTP-запросы к серверу робота не поддерживают авторизацию. Вам следует самостоятельно позаботиться о его защите на сетевом уровне.
HTTP-запросы от сервиса Webim к серверу не содержат особых заголовков. Заголовок content-type
имеет значение application/json
. Ответы от сервера робота ожидаются в одинаковом формате независимо от событий.
Начало нового чата (new_chat
)
Событие new_chat срабатывает в момент назначения нового чата на робота.
URL-адрес сервера, куда передаются данные, берется из настроек бота (см. выше).
Формат передаваемых данных: POST-запрос на сервер робота, данные в формате JSON.
Структура передаваемых данных:
{ "event": "new_chat", "chat": { "id": (string) }, "visitor": { "id": (string) }, "messages": [(message), (message)...] }
Пример запроса:
{ "event": "new_chat", "chat": { "id": "23f56796-4db8-4284-a6e4-4c6865918bb6" }, "visitor": { "id": "51b6d2d74ac24af38cbfbb7cf5529845" }, "messages": [ { "kind":"visitor", "text":"Мне нужна ваша помощь" } ] }
Описание параметров:
Название параметра | Тип | Описание |
---|---|---|
event | String | Описывает, какое событие произошло. |
chat.id | String | Уникальный идентификатор чата. Представлен в формате UUID4. Данный идентификатор назначается чату на фронтэнде и не совпадает с другим идентификатором чата, который отображается в истории диалога. Пример: "7388e3b3-4065-4953-8638-2d41d6e6c730" |
visitor.id | String | Уникальный идентификатор пользователя. |
messages | String | Массив из сообщений пользователя, которые были отправлены в чат до его появления в РМО (например, во время выбора отдела в каналах). |
Сообщение (message) имеет вид:
{ "kind": (string), "text*": (string), "response*": { "button": (button) } }
Пример:
{ "kind": "keyboard_response", "response": { "button":{ "id":"2", "text":"Обратиться в техническую поддержку" } } }
Описание параметров:
Название параметра | Пример | Описание |
---|---|---|
kind | String | visitor или keyboard_response . |
text | String | Текст сообщения пользователя. Присутствует, если kind = visitor . |
response | Object | Описывает ответ пользователя на keyboard сообщение. Присутствует, если kind = keyboard_response . |
response.button | Button | Описывает нажатую кнопку. |
Тип button имеет вид:
{ "id": (string), "text": (string) }
Пример:
{ "id": "4", "text": "Перевести чат на оператора" }
Описание параметров:
Название параметра | Пример | Описание |
---|---|---|
id | String | Уникальный идентификатор кнопки (не более 24 символов, не может быть пустым). |
text | String | Текст на кнопке. |
Новое сообщение от клиента, нажатие кнопки (new_message
)
Событие new_message инициируется в момент прихода нового сообщения от пользователя в чат (после нажатия пользователем кнопки), назначенный на робота.
URL-адрес сервера, куда передаются данные, берется из настроек бота (см. выше).
Формат передаваемых данных: POST-запрос на сервер робота, данные в формате JSON.
Структура передаваемых данных зависит от типа сообщения пользования (значения параметра kind
): оно может принимать значение visitor
(если пользователь отправил текстовое сообщение) и keyboard_response
(если пользователь выбрал ответ из предложенных ему через кнопочное меню).
Структура передаваемых данных (тип сообщения visitor
):
{ "event": "new_message", "chat": { "id": (string) }, "kind": (string), "text": (string) }
Пример:
{ "event": "new_message", "chat": { "id": "9401b039-ace3-4619-b884-a24e0aaf7adb" }, "kind": "visitor", "text": "Здравствуйте, не могли бы вы мне помочь?" }
Структура передаваемых данных (тип сообщения keyboard_response
):
{ "event": "new_message", "chat": { "id": (string) }, "kind": (string), "response": { "button": (button) } }
Пример:
{ "event": "new_message", "chat": { "id": "9401b039-ace3-4619-b884-a24e0aaf7adb" }, "kind": "keyboard_response", "response": { "button": { "id": "937bec4863154a2fb0889ff1320d1e2f", "text": "Перевести диалог на Отдел продаж" } } }
Описание параметров:
Название параметра | Тип | Описание |
---|---|---|
event | String | Описывает, какое событие произошло. Не может быть NULL. |
chat.id | String | Уникальный идентификатор чата. Представлен в формате UUID4. Данный идентификатор назначается чату на фронтэнде и не совпадает с другим идентификатором чата, который отображается в истории диалога. Не может быть NULL. Пример: "7388e3b3-4065-4953-8638-2d41d6e6c730" |
kind | String | Обязательно принимает одно из значений: visitor или keyboard_response . |
text | String | Текст сообщения пользователя. Не может быть NULL, если kind = visitor . |
response.button | Button | Описывает нажатую кнопку - ответ пользователя на keyboard-сообщение. Не может быть NULL, если kind = keyboard_response . |
button.id | String | Идентификатор нажатой кнопки. Не может быть NULL, если kind = keyboard_response . |
button.text | String | Текст, содержащийся в нажатой посетителем кнопке. Не может быть NULL, если kind = keyboard_response . |
Ожидаемые ответы на запросы
Успех: статус 200
На запрос со стороны сервиса Webim сервер робота должен ответить объектом JSON с параметрами:
Название параметра | Тип | Описание |
---|---|---|
has_answer | Boolean |
|
messages | Array | Массив из сообщений. |
Запрос с событием new_chat допускает пустое тело ответа. При пустом теле ответа на new_message либо при коде ответа от 400 до 599 на любой тип события чат переводится в общую очередь.
Webim ждёт ответа от сервера робота в течение 5 секунд (этот срок прописан в коде сервиса). После этого чат переводится в общую очередь.
Сообщение (message) имеет вид:
{ "kind": (string), "text*": (string), "buttons*": [ [(button), (button) ...], ... ] }
Пример:
{ "kind": "operator", "text": "Здравствуйте, отвечу на все ваши вопросы." }
Описание параметров:
Название параметра | Пример | Описание |
---|---|---|
kind | String | operator или keyboard . |
text | String | Сообщение от оператора Присутствует, если kind = operator . |
buttons | Array of arrays | Массив массивов кнопок вида [[b1, b2], [b3]]. Запись означает, что кнопки b1, b2 расположены на одной строке. Присутствует, если kind = keyboard . |
Примеры ответов
Робот знает ответ:
{ "has_answer": true, "messages": [ { "kind": "operator", "text": "Мы работаем над вашей проблемой" }, { "kind": "keyboard", "buttons": [ [ { "id": "call_agents", "text": "Обратиться к операторам" } ], [ { "id": "call_agent", "text": "Обратиться к оператору" } ] ] } ] }
Выглядит это так:
Робот не знает ответа:
{ "has_answer": false }