External Bot API 2.0

В Webim версии 10.1 подключение "внешних" или "умных" ботов, которые размещаются на внешнем относительно Webim сервере, происходит посредством External Bot API 2.0. При этом предыдущая версия External Bot API сохранена в 10.1 для поддержки совместимости, то есть поддерживаются обе версии API.

Содержание статьи:

Описание

В отличие от предыдущей версии, External Bot API 2.0 является асинхронным.

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

Общая логика

На робота 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/{path}

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

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

Пример 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": "unauhorized"}

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

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

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

Поле Тип Пример Описание Обязательный
error String "incorrect-request" Код ошибки. Да
desc String "Запрос сформирован неверно, возможно, пропущены необходимые параметры." Описание ошибки на английском языке. Не является обязательным. Нет

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

Path: /send_message
Тип запроса: POST

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

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

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

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

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

Поле Тип Описание
message JSON Объект Message.
chat_id Integer или String Идентификатор чата.

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

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

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

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

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

Поле Тип Пример Описание
kind String "operator" Тип сообщения. В данном случае это текстовое сообщение, где kind = "operator". Все существующие типы сообщений есть в данной статье.
text String "Здравствуйте. Мне нужна ваша консультация по тарифам" Содержание текстового сообщения.

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

Код ошибки Описание
message-not-created Не удалось создать сообщение. Возможно, запрос был сформирован неверно.
incorrect-request Запрос сформирован неверно, возможно, пропущены необходимые параметры
chat-not-found Чат с указанным id не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

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

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

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

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

Поле Тип Пример Описание
kind String "file_operator" Тип сообщения. В данном случае это сообщения оператора, содержащие отправленные файлы. Все существующие типы сообщений есть в данной статье.
data.url String "https://somesite.com/img54-65-79.jpg" URL-адрес файла.
data.name String "image.png" Имя файла.
Имя должно содержать расширение. То, файлы с каким расширением могут отправляться ботом, определяется параметром robot_allowed_upload_file_types настроек account config,
data.media_type String "application/pdf" Internet Media Type. Файлы с каким medai type могут отправляться ботом, определяется параметром robot_allowed_upload_file_content_types. Также могут быть наложены ограничения на размер файлов, отправляемых ботом (подробности см. в статье Обработка файлов, загружаемых в чат).

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

Код ошибки Описание
insecure-file-type Файл не прошел проверку безопасности
incorrect-image Некорректный файл с изображением
media-type-not-match Несоответствие заявленного Media Type с фактическим
max-file-size-exceeded Размер файла превышает допустимый
message-not-created Не удалось создать сообщение. Возможно, запрос был сформирован неверно.
incorrect-request Запрос сформирован неверно, возможно, пропущены необходимые параметры
chat-not-found Чат с указанным id не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

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

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

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

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

Поле Тип Описание
kind String Тип сообщения. Сообщения с кнопками являются типами keyboard или keyboard_response. Все существующие типы сообщений есть в данной статье.
buttons list Массив массивов кнопок. Позволяет группировать наборы кнопок, предлагаемые посетителю, в строки.

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

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

Поле Тип Пример Описание
id String "937bec4863154a2fb0889ff1320d1e2f" Идентификатор кнопки.
text String "Задать вопрос оператору" Текст кнопки.

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

Код ошибки Описание
incorrect-buttons Сообщение с кнопками составлено неверно
message-not-created Не удалось создать сообщение. Возможно, запрос был сформирован неверно.
incorrect-request Запрос сформирован неверно, возможно, пропущены необходимые параметры
chat-not-found Чат с указанным id не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

Перевод чата

Path: /redirect_chat
Тип запроса: POST

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

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

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

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

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

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

Поле Тип Пример Описание
operator_id Integer 168524 Идентификатор оператора.
chat_id Integer или String 426 Идентификатор чата.

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

Код ошибки Описание
operator-not-found Оператор с указанным id не найден
target-is-offline Оператор в состоянии offline
incorrect-request Запрос сформирован неверно, возможно, пропущены необходимые параметры
chat-not-found Чат с указанным id не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

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

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

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

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

Поле Тип Пример Описание Обязательный
dep_key String "sales_department" Идентификатор отдела. Да
chat_id Integer или String 168 Идентификатор чата. Да
allow_redirect_to_offline_dep Boolean "false" Переводить ли чат на отдел, если в нем все операторы офлайн. Соответственно, обращения переводятся и при операторах в остальных статусахНевидимке и прочих. По умолчанию false. Нет
allow_redirect_to_invisible_dep Boolean "true" Переводить ли чат на отдел, если в нем нет операторов онлайн — достаточно, чтобы оператор был в статусе Невидимка или аналогичных ему. Если включён параметр allow_redirect_to_offline_dep, тогда функциональность allow_redirect_to_invisible_dep включается автоматически, так как это более сильное свойство. Таким образом, от предыдущего параметра данный параметр отличается тем, что при его включении чаты не переводятся только в те отделы, где все операторы находятся в статусе Офлайн. По умолчанию true. Нет

Выставлять значение true одновременно параметру allow_redirect_to_offline_dep и параметру allow_redirect_to_invisible_dep нельзя.

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

Код ошибки Описание
department-not-found Отдел с указанным id не найден
target-is-offline Отдел в состоянии offline
incorrect-request Запрос сформирован неверно, возможно, пропущены необходимые параметры
chat-not-found Чат с указанным id не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

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

Path: /close_chat
Тип запроса: POST

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

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

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

{
    "chat_id":462
}

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

Поле Тип Пример Описание
chat_id Integer или String 241 Идентификатор чата

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

Код ошибки Описание
incorrect-request Запрос сформирован неверно, возможно, пропущены необходимые параметры
chat-not-found Чат с указанным id не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

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

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

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

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

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

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

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

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

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

Webim обращается на URL-адрес бота, который задаётся в настройках Панели управления при создании бота (см. пункт 5).

Для этих запросов авторизация не требуется.

Для повышения безопасности в URL бота (пункт 5) можно добавить секретный ключ. Он вставляется в URL следующим образом: вместо address указывается address/secret_key, где secret_key – некоторая последовательность символов.

В случае, если запрос со стороны Webim не проходит на бота, сервер Webim будет пытаться отправить его ещё четыре раза после неудачи: сначала через 2 секунды после неудачной попытки, потом через 4, 8 и 16 секунд (отсчёт с последней неудачной попытки).

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

В случае успеха бот должен дать следующий ответ:
200 OK

Тело ответа бот-сервера на запрос Webim должно содержать:

{
   "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/id000",
            "site":"https://webim.ru"
        }
    }
    "messages": [
        Message,
        Message,
        ...
    ]
}

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

Поле Тип Пример Описание
event String "new_chat" Тип события.
chat_id Integer или String 247 Идентификатор чата.
visitor_id String "03e1c040d8214bfa8ccfbb053186a24a" Идентификатор посетителя.
visitor.fields JSON "{"name": "Владислав", "phone": "+79113258746", ...} Известная информация о посетителе в виде пар ключ-значение. Все поля можно посмотреть здесь.
messages Массив объектов Message Приведены ниже в описании события new_message Сообщения, которые присылал посетитель и которые накопились к моменту, когда чат был назначен на бота (сообщение из каналов, из виджета, если включён запрос контактных данных перед началом чата).

Новое сообщение

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

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

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

Поле Тип Пример Описание
event String "new_message" Тип события.
message Message Приведены ниже Объект Message.
chat_id Integer или String 247 Идентификатор чата.

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

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

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

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

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

Поле Тип Пример Описание
id String "feb8e0f7fe08486db2494c2d5058fd33" Идентификатор сообщения на стороне Webim.
kind String "operator" Тип сообщения. Все типы поддерживаемых Webim сообщений перечислены в этой статье. При использовании External Bot API 2.0 применимы не все из них.
text String "Могу ли я вам помочь?" Текст сообщения.

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

Бот должен вернуть ответ {"result": "ok"} для сообщений, где media_type = json.

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

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

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

Поле Тип Пример Описание Обязательный
id String "6355ba4163f947b9b77f7e65ce4317a7" Идентификатор сообщения на стороне Webim. Да
kind String "file_visitor" Тип сообщения, в данном случае файл, отправленный посетителем (file_visitor). Все существующие типы сообщений перечислены в этой статье. Да
data.id String "81f0488" Идентификатор файла. Да
data.state String "upload" Состояние, в котором находится отправленный файл (upload — если находится в процессе загрузки, ready — если загрузка завершена). Да
data.name String "somefile.pdf" Название файла Нет
data.media_type String "application" Internet Media Type. Нет
data.size Integer 12350 Размер файла в байтах. Нет
data.progress Integer 95 Степень загрузки файла с data.state = upload. Указывается в процентах. Нет
data.url String "https://yoursite.com/content/nicepicture.jpg" URL-адрес загруженного файла (при data.state = "ready"). Нет

Нажатие на кнопку

Запрос содержит выбранную посетителем кнопку.

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

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

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

Поле Тип Пример Описание
id String "ddaa8401e1ef4910abb3657f3ea09683" Идентификатор сообщения на стороне Webim.
kind String "keyboard_response" Тип сообщения. Все типы сообщений в этой статье.
data.button Button Объект Button Нажатая кнопка.
data.request.messageId String "fede9187f3da41c9849976a01a40d899" Идентификатор сообщения, кнопка которого была нажата.

Обновление сообщения

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

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

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

Поле Тип Пример Описание
event String "message_updated" Тип события.
message Message Объект Message. Его вид аналогичен виду в событии new_message Содержание объекта Message после обновления.
chat_id Integer или String 2547 Идентификатор чата.