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 к серверу в заголовке содержат следующие параметры:

X-Bot-API-Dialect — "диалект" API (в данном случае Webim Standard);
X-Bot-API-Version — версия API (в данном случае 1.0);
X-Webim-Version — полная версия Webim (например: 10.3.11)

Заголовок 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)
}

Пример содержимого:

{
    "kind": "operator",
    "text": "Здравствуйте, отвечу на все ваши вопросы."
}

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

Название параметра	Тип	Описание
`kind`	`String`	Значение `kind` должно быть только `operator`.
`text`	`String`	Сообщение от оператора.

Кнопочное сообщение (message) имеет вид:

{
    "kind": (string),
    "buttons": [
        [
            {
                "id": (string),
                "text": (string)
            }
        ]
    ]
}

Пример содержимого:

{
    "kind": "keyboard",
    "buttons": [
        [
            {
                "id": "ask_agent",
                "text": "Спросить у оператора"
            }
        ],
        [
            {
                "id": "ask_department",
                "text": "Обратиться в отдел"
            }
        ]
    ]
}

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

Название параметра	Тип	Описание
`kind`	`String`	Значение `kind` должно быть только `keyboard`.
`buttons`	`Array of Arrays`	Массив массивов кнопок вида `[[b1, b2], [b3]]`. Запись означает, что кнопки `b1`, `b2` расположены на одной строке.

Объект button имеет вид:

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

Пример содержимого объекта button:

{
    "id": "4",
    "text": "Перевести чат на оператора"
}

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

Название параметра	Тип	Описание
`id`	`String`	Идентификатор кнопки. Может быть не длиннее 24 символов.
`text`	`String`	Текст кнопки

Примеры отчётов

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

{
    "has_answer": true,
    "messages": [
        {
            "kind": "operator",
            "text": "Мы работаем над вашей проблемой"
        },
        {
            "kind": "keyboard",
            "buttons": [
                [
                    {
                        "id": "call_agents",
                        "text": "Обратиться к операторам"
                    }
                ],
                [
                    {
                        "id": "call_agent",
                        "text": "Обратиться к оператору"
                    }
                ]
            ]
        }
    ]
}

Выглядит это так:

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

{
    "has_answer": false
}

External Bot API 1.0

Общая логика

Настройка

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

Начало нового чата (new_chat)

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

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

Примеры отчётов

Начало нового чата (`new_chat`)

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