External Bot API 2.0

В отличие от предыдущей версии, External Bot API 2.0 является асинхронным.Робот принимает от пользователя вопрос и отправляет его на внешний сервер. Сервер генерирует ответ и присылает его обратно в сервис Webim, сервис показывает ответ пользователю. При этом сервер Webim не находится в ожидании ответа с сервера бота: тот сам пришлёт ответ, когда сформулирует его. В отличие от предыдущей версии External Bot API, отвечать на запрос сразу же необязательно, необходимо лишь вернуть код 200 при успешном выполнении запроса, а ответ можно сформулировать потом.

---

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

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

---

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

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

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

---

Структура 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 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'}

---

{
   "result":"ok"
}

{
    "event":"new_chat",
    "chat":{
        "id":452
    },
    "visitor":{
        "id":"03e1c040d8214bfa8ccfbb053186a24a",
        "fields":{
            "email":"support@webim.ru",
            "id":"asdf123",
            "icq":"123123123",
            "login":"somelogin",
            "name":"asdf123",
            "phone":"+7 (812) 385-53-37",
            "profile_url":"https://vk.com/webimru",
            "site":"https://webim.ru"
        }
    }
    "messages": [
        Message,
        Message,
        ...
    ]
}

{
    "event":"new_message",
    "message": Message,
    "chat_id":245
}

{
    "id":"feb8e0f7fe08486db2494c2d5058fd33",
    "kind":"visitor",
    "text":"Здравствуйте"
}

{
    "id":"c3e19d57f64e43c3afabdef2ef4e4054",
    "kind":"file_visitor",
    "data":{
        "id":"81f0488",
        "state":"upload",
        "progress": 50,
        "size":560
        "url":"https://yoursite.com/content/file.txt",
    }
}

{
    "id":"c3e19d57f64e43c3afabdef2ef4e4054",
    "kind":"file_visitor",
    "data":{
        "id":"81f0488",
        "state":"upload",
        "progress": 89,
        "size":560
        "url":"https://yoursite.com/content/file.txt",
    }
}

{
    "id":"c3e19d57f64e43c3afabdef2ef4e4054",
    "kind":"file_visitor",
    "data":{
        "id":"81f0488",
        "state":"ready",
        "name":"file.txt",
        "content_type":"text",
        "size":560
        "url":"https://yoursite.com/content/file.txt",
    }
}

{
    "id":"ddaa8401e1ef4910abb3657f3ea09683",
    "kind":"keyboard_response",
    "data":{
        "button":{
            "id":"937bec4863154a2fb0889ff1320d1e2f",
            "text":"Задать вопрос оператору"
        },
        "request":{
            "messageId":"fede9187f3da41c9849976a01a40d899"
        }
    }
}

{
    "event": "message_updated",
    "message": Message,
    "chat_id": 8754
}