External Bot API 2.0

Общая логика

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

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

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

Настройка

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

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

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

Базовый URL

Структура URL со стороны Webim:

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

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

Перечень эндпоинтов External Bot API 2.0:

• /api/bot/v2/send_message
• /api/bot/v2/redirect_chat
• /api/bot/v2/close_chat
• /api/bot/v2/file/{guid}?hash={hash}

Пример URL:

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

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

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

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

Запросы к Webim

Ниже изложены примеры и описания запросов к Webim Server.
Запросы отправляются на URL, указанный при создании бота.

Авторизация осуществляется через header с использованием токена (см. пункт 7). Для каждого бота генерируется новый токен.

Формат авторизации токена:

Authorization: Token {token}

Пример авторизации токена:

Authorization: Token ac650a3c369a4b9599ad52ab71943712

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

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

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

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

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

Если отсутствует токен, сервер вернёт ошибку:

{"error": "unauthorized"}

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

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

Описание полей ошибок:

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

Path: /send_message
Тип запроса: POST
Content-type: application/json
Query-string параметры: не нужны

Пример URL при отправке ботом сообщения посетителю:

POST https://mycompany.webim.ru/api/bot/v2/send_message

Пример тела запроса при отправке ботом сообщения:

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

Описание полей объекта в ответе при отправке ботом сообщения:

Объект Message может иметь разный набор полей в зависимости от типа сообщения.

Текстовое сообщение

Пример содержимого объекта Message в текстовом сообщении:

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

Описание полей объекта Message в текстовом сообщении:

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

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

Пример содержимого объекта Message для файлового сообщения:

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

Описание полей объекта Message для файлового сообщения:

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

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

Пример содержимого объекта Message для сообщения с кнопками:

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

Описание полей объекта Message для сообщения с кнопками:

В свою очередь Buttons состоит из массивов Button.

Каждый объект Button содержит в массиве следующие параметры:

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

Перевод чата

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

Path: /redirect_chat
Тип запроса: POST
Content-type: application/json
Query-string параметры: не нужны

Пример URL при переводе чата:

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

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

Пример тела запроса при переводе чата на оператора:

{
    "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
}

Описание полей объекта в ответе на запрос при переводе чата на отдел:

Из двух параметров — allow_redirect_to_offline_dep и allow_redirect_to_invisible_dep — в теле запроса может присутствовать только один; в противном случае в ответ на запрос сервер вернёт ошибку.

Описание возможных ошибок при переводе чата на отдел:

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

Path: /close_chat
Тип запроса: POST
Content-type: application/json
Query-string параметры: не нужны

Пример URL при закрытии чата:

POST https://mycompany.webim.ru/api/bot/v2/close_chat

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

{
    "chat_id":462
}

Описание полей объекта в ответе на запрос при закрытии чата:

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

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

При помощи данного запроса клиент может скачать файл, присланный посетителем в чате с ботом.

Path: /file/{guid}?hash={hash}
Тип запроса: GET
Query-string параметры: hash – посчитанный hash

Пример URL при скачивании файлов:

GET https://mycompany.webim.ru/api/bot/v2/file/7d5d197ef3ee4b29be6b1a668977ccdc?hash=e96881ac8db26e8570cd9c032900cd3e0b08128132e61c844102633c64a69b2a

где:

• 7d5d197ef3ee4b29be6b1a668977ccdc – guid (уникальный идентификатор) файла;
• e96881ac8db26e8570cd9c032900cd3e0b08128132e61c844102633c64a69b2a – hash-сумма файла, помогающая обезопасить файл от нежелательного скачивания

Результатом обращения на данный URL будет скачивание клиентом файла, присланного посетителем в чате. Механизм скачивания файлов, присланных посетителем, описан в статье.

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

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