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:

  1. Создайте оператора в системе через интерфейс. Инструкцию по созданию оператора см. здесь.
  2. Перейдите в настройки Вашего аккаунта, выберите раздел Боты.
  3. В открывшемся окне нажмите на кнопку Создать нового бота.
  4. Заполните информацию о вашем боте, в поле Ссылка на внешний API впишите URL-адрес внешнего сервера робота.
  5. Сохраните изменения.

Логика работы робота

Когда в системе происходят различные события, то логика робота-оператора в 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
  • true — робот может ответить на сообщение клиента;
  • false — робот не знает ответ, чат будет переведен в общую очередь.
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
}