External API 1.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": "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.
Структура передаваемых данных (в зависимости от сообщения пользователя):

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

Пример:

{
    "event": "new_message",
    "chat": {
        "id": "9401b039-ace3-4619-b884-a24e0aaf7adb"
    },
    "kind": "visitor",
    "text": "Здравствуйте, не могли бы вы мне помочь?"
}

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