Подключение внешних роботов через External API 1.0

Описание

External API 1.0 — это механизм подключения роботов к сервису Webim. Программно-аппаратная часть (бэкенд) таких роботов находится на внешнем относительно сервиса Webim сервере. Общение между сервисом и аппаратно-вычислительной частью происходит через HTTP-запросы из сервиса Webim на этот сервер.

Робот External API принимает от пользователя вопрос и отправляет его на внешний сервер. Сервер генерирует ответ и присылает его обратно в сервис Webim, сервис показывает ответ пользователю. После этого робот снова ожидает вопрос от пользователя.

Если программно-аппаратная часть (бэкенд) робота перестала отвечать, не знает ответа или возникли другие проблемы, то чат переходит в общую очередь.

External API 1.0 является синхронным. Сервис ожидает ответ от робота в теле response.

В версии Webim 10.0 робот получил название «умный бот». Теперь для создания робота существует административная панель.

Общая логика

На робота External 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 String Описывает, какое событие произошло.
chat.id String Уникальный идентификатор чата.
visitor.id String Уникальный идентификатор пользователя.
messages String Массив из сообщений пользователя, которые были отправлены в чат до его появления в РМО (например, во время выбора отдела в каналах).

Сообщение (message) имеет вид:

{
    "kind": (string),
    "text*": (string),
    "response*": {
        "button": (button)
    }
}

Описание параметров:

Название параметра Пример Описание
kind String visitor или keyboard_response.
text String Текст сообщения пользователя.
Присутствует, если kind = visitor.
response Object Описывает ответ пользователя на keyboard сообщение.
Присутствует, если kind = keyboard_response.
button Button Описывает нажатую кнопку.

Тип button имеет вид:

{
    "id": (string),
    "text": (string)
}

Описание параметров:

Название параметра Пример Описание
id String Идентификатор кнопки (не более 24 символов).
text String Текст на кнопке.

Новое сообщение от клиента, нажатие кнопки (new_message)

Событие new_message инициируется в момент прихода нового сообщения от пользователя в чат (после нажатия пользователем кнопки), назначенный на робота.

URL-адрес сервера, куда передаются данные, берется из настроек бота (см. выше).

Формат передаваемых данных: POST-запрос на сервер робота, данные в формате JSON.
Структура передаваемых данных (в зависимости от сообщения пользователя):

{
    "event": "new_message",
    "chat": {
        "id": (string)
    },
    "kind": (string),
    "text*": (string),
    "response*": {
        "button": (button)
    }
}

Описание параметров:

Название параметра Тип Описание
event String Описывает, какое событие произошло.
chat.id String Уникальный идентификатор чата.
kind String visitor или keyboard_response.
text String Текст сообщения пользователя.
Присутствует, если kind = visitor.
response Object Описывает ответ пользователя на keyboard сообщение.
Присутствует, если kind = keyboard_response.
button Button Описывает нажатую кнопку.

Ожидаемые ответы на запросы

Успех: статус 200

На запрос со стороны сервиса Webim сервер робота должен ответить объектом JSON с параметрами:

Название параметра Тип Описание
has_answer Boolean
  • true — робот может ответить на сообщение клиента;
  • false — робот не знает ответ, чат будет переведен в общую очередь.
messages Array Массив из сообщений.

Запрос с событием new_chat допускает пустое тело ответа. В иных случаях чат переводится в общую очередь.
Webim ждёт ответа от сервера робота в течение 5 секунд (этот срок прописан в коде сервиса). После этого чат переводится в общую очередь.

Сообщение (message) имеет вид:

{
    "kind": (string),
    "text*": (string),
    "buttons*": [ [(button), (button) ...], ... ]
}

Описание параметров:

Название параметра Пример Описание
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_agent",
                    "text": "Обратиться к оператору"
                }
            ]
        }
    ]
}

Робот не знает ответа:

{
    "has_answer": false
}