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

• '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":"Мне нужна ваша помощь"
            }
    ]
}

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

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

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

Пример тела запроса:

{
    "kind": "keyboard_response",
    "response": {
        "button":{
            "id":"2",
            "text":"Обратиться в техническую поддержку"
        }
    }
}

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

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

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

Пример тела запроса:

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

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

Новое сообщение от клиента, нажатие кнопки (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": "Перевести диалог на Отдел продаж"
        }
    }
}

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

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

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

При любом другом ответе на запрос чат будет переведён в общую очередь.

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

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

Текстовое сообщение (message) имеет вид:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "has_answer": false
}