External Bot API 2.0

Общая логика

На робота External Bot API автоматически назначаются все онлайн-чаты, которые поступают в отдел, в который этот робот добавлен.

Онлайн-статус робота влияет на общий онлайн-статус системы:

• если робот — «онлайн», то он будет принимать все чаты от пользователей, и кнопка на сайте будет «онлайн»;
• если робот — «невидимка» и нет операторов онлайн, то он будет принимать все чаты от пользователей, но кнопка на сайте будет показываться «офлайн»;
• если робот — «офлайн», то он не будет принимать никакие чаты (и не будет влиять на онлайн-статус кнопки).

Настройка

Инструкция по настройке и подключению умного бота актуальна для сервиса Webim версии 10.1.

Для подключения внешнего робота к сервису Webim:

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

Базовые URL

URL со стороны Webim:

https://{hostname}/api/bot/v2/{command}

Где {hostname} — имя хоста, на котором размещается сервер Webim, вида {account}.webim.ru для облачных клиентов и chat.mycompany.com для hosted; {command} — команда API.

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

https://mycompany.webim.ru/api/bot/v2/redirect_chat 

Данный запрос переведёт чат на оператора.

URL со стороны бота:

задается в настройках

Запросы с бот-сервера к Webim

Ниже изложены примеры и описания запросов к Webim Server.
Запросы отправляются на URL, указанный при создании бота.
Авторизация осуществляется через header с использованием URL внешнего бота и токена.

Обработка ошибок

Ответ Webim в случае успеха приходит с HTTP-кодом 200:

{
   "result":"ok"
}

Если запрос не проходит валидацию, возвращается HTTP-код 400.
При ошибке авторизации возвращается HTTP-код 401.
Если робот с заданным токеном не найден, возвращается HTTP-код 403.
Если использован метод не из описанных ниже, возвращает ошибку 404 {'error': 'method-not-found'}.
При разных внутренних ошибках сервера возвращается ошибка с HTTP-кодом 500.
Если сервер получает неверный ответ, возвращает 502.

Ошибки возвращаются в формате:

{
    "error":"код ошибки"
}

Прочие ошибки приходят с HTTP-кодом 200 в формате:

{
    "error": (буквенный код ошибки),
    "desc": (текстовое описание ошибки)
}

Описание полей:

Ответ чат-бота на вопрос посетителя

URL: /api/bot/v2/send_message

Тип запроса: POST

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

{
    "message":"Message",
    "chat_id":3058
}

Описание полей:

Поле message может содержать в себе разные виды данных и, соответственно, иметь разный набор полей.

Обычное сообщение

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

{
    "kind":"operator",
    "text":"Здравствуйте, чем я могу вам помочь?"
}

Описание полей:

Описание возможных ошибок:

Файловое сообщение

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

{
    "kind":"file_operator",
    "data":{
        "url":"https://webim.ru/wp-content/uploads/2019/04/diagram.png",
        "name":"diagram.png",
        "media_type":"png"
    }
}

Описание полей:

Описание возможных ошибок:

Сообщение с кнопками

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

{
    "kind":"keyboard",
    "buttons":[
        [
            {
                "text":"Перевести на техподдержку",
                "id":"fedc60c4dc0d4348b48b524d"
            }
        ],
        [
            {
                "text":"Перевести на отдел продаж",
                "id":"574f2caad88a41a7a2d6b667"
            }
        ]
    ]
}

Описание полей:

В свою очередь Buttons состоит из массивов Button.
Каждый массив Button содержит следующие параметры:

Описание возможных ошибок:

Перевод чата

URL: api/bot/v2/redirect_chat
Тип запроса: POST

Перевод на оператора

Запрос:

{
    "operator_id":486254,
    "chat_id":195
}

Описание полей:

Описание возможных ошибок:

Перевод на отдел

Запрос:

{
    "dep_key":"sales_department",
    "chat_id":425,
    "allow_redirect_to_offline_dep":false,
    "allow_redirect_to_invisible_dep":true
}

Описание полей:

Описание возможных ошибок:

Закрытие чата

URL: /api/bot/v2/close_chat
Тип запроса: POST

Запрос:

{
    "chat_id":462
}

Описание полей:

Описание возможных ошибок:

Скачивание файлов

URL: /file/{guid}?hash={hash}
Тип запроса: GET

Ссылка на скачивание файла приходит внутри сообщения, у которого kind = file_visitor.

Если не прошла авторизация с хэшем файла, вернёт ошибку: 403 {'error': 'access-denied'}
Если файл не найден или использован метод не 'file', выдаст ошибку: 404 {'error': 'file-not-found'}