Перейти к содержанию

Умный Бот 2.0

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

Описание

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


Общая логика

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

  • если робот - Онлайн, то он будет принимать все чаты от пользователей, и кнопка на сайте будет Онлайн;

  • если робот - Невидимка и нет операторов онлайн, то он будет принимать все чаты от пользователей, но кнопка на сайте будет показываться Офлайн;

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


Настройка

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

Для подлкючения внешнего бота к сервису 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.

Перечень эндпоинтов Умный Бот 2.0:

Пример URL:

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

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

N.B.

URL со стороны бота задаётся в настройках


Запросы к Webim

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

Авторизация

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

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

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": (текстовое описание ошибки)
}

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

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

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

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 JSON Объект Message Да
chat_id Integer Идентификатор чата Да

Объект 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 beautifulpicture.jpg Имя файла.
Имя должно содержать расширение.
Бот может отправлять файлы с расширениями, заданными параметром robot_allowed_upload_file_types настроек account config.
Да
data.media_type String image/jpeg Internet Media Type.
Бот может отправлять файлы с media 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 Не удалось создать сообщение. Возможно, запрос был сформирован неверно.
chat-not-found Чат с указанным id либо не был найден, либо не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.).
incorrect-request Запрос сформирован неверно. Возможно, пропущены необходимые параметры.

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

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

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

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

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

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

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

Поле Тип Пример Описание Обязательный
id String 937bec4863154a2fb0889ff1 Идентификатор кнопки. Может содержать только латинские буквы, цифры, символы дефиса и нижнего подчёркивания и должен быть не более 24 символов в длину. ID кнопки, генерируемый сервером Webim, имеет формат UUID4, а ID, генерируемый сторонними ботами, только проверяется на соответствие данным выше критериям. Да
text String Задать вопрос оператору Текст кнопки. Да

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

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

Перевод чата

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

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
}

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

Поле Тип Пример Описание Обязательный
operator_id Integer 168524 Идентификатор оператора. Да
chat_id Integer 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 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. Нет

N.B.

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

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

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

Перевод в общую очередь

Пример тела запроса при переводе чата в общую очередь:

{
  "chat_id": 425
}

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

Поле Тип Пример Описание Обязательный
chat_id Integer 426 Идентификатор чата. Да

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

Path: /close_chat

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

Content-type: application/json

Query-string параметры: не нужны

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

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

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

{
    "chat_id":462
}

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

Поле Тип Пример Описание Обязательный
chat_id Integer 241 Идентификатор чата Да

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

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

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

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

Path: /file/{guid}?hash={hash}

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

Query-string параметры: hash – посчитанный hash

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

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

  • 7d5d197ef3ee4b29be6b1a668977ccdcguid (уникальный идентификатор) файла;

  • e96881ac8db26e8570cd9c032900cd3e0b08128132e61c844102633c64a69b2a – hash-сумма файла, помогающая обезопасить файл от нежелательного скачивания

Результатом обращения на данный 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 секунд (отсчёт с последней неудачной попытки).

HTTP-запросы от сервиса Webim к серверу в заголовке содержат следующие параметры:

  • X-Bot-API-Dialect — "диалект" API (в данном случае Webim Standard);

  • X-Bot-API-Version — версия API (в данном случае 2.0);

  • X-Webim-Version — полная версия Webim (например: 10.3.11)

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

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

200 OK

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

{
   "result":"ok"
}

В случае получения другого ответа чат будет переведен в общую очередь.

Назначение чата на робота

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

Content-type: application/json

Query-string параметры: не нужны

Вызывается при создании чата либо при переводе чата на робота.

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

{
    "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 String new_chat Тип события. Да
chat.id Integer 247 Идентификатор чата. Да
visitor.id String 03e1c040d8214bfa8ccfbb053186a24a Псевдоуникальный идентификатор посетителя, который ему всегда назначает Webim. Да
visitor.fields JSON {"name": "Владислав", "phone": "+79113258746", ...} Известная информация о посетителе в виде пар ключ-значение. Идентификатор посетителя внутри visitor.fields передаётся в Webim фронтэндом, может быть произвольного вида и не быть уникальным. Если отсутствует visitor.fields, то идентификатор, соответственно, отсутствует. В случае наличия visitor.fields идентификатор является обязательным полем, все остальные поля — нет. Описание всех полей visitor.fields можно посмотреть здесь. Нет
messages Массив объектов Message Приведены ниже в описании события new_message Сообщения, которые присылал посетитель и которые накопились к моменту, когда чат был назначен на бота (сообщение из каналов, из виджета, если включён запрос контактных данных перед началом чата). Нет

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

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

Content-type: application/json

Query-string параметры: не нужны

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

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

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

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

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

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

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

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

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

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

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

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

По мере отправки файла будет отправляться не один, а несколько запросов, количество которых зависит от размера файла: чем большего он размера, тем длительнее загрузка. В процессе загрузки файла (при значении upload в поле state) каждый новый запрос будет содержать обновлённое значение процентов загрузки файла (поле progress). Последний запрос при отправке файла будет иметь значение ready в поле state, что значит, что файл отправлен.

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

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

Описание полей объекта 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.state = upload может отсутствовать. Нет
data.media_type String application/pdf Internet Media Type. При data.state = upload может отсутствовать. Нет
data.size Integer 12350 Размер файла в байтах. Нет
data.progress Integer 95 Степень загрузки файла при data.state = upload. Указывается в процентах. Нет
data.url String https://yoursite.com/content/document.pdf 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 Нажатая посетителем кнопка. В некоторых каналах общения (например, WhatsApp, ВКонтакте) кнопки выводятся в виде нумерованного списка (текстом). При таком формате посетитель выбирает кнопку путём отправки сообщения с номером кнопки. Иными словами, кнопка считается выбранной только при условии, что кнопка есть в перечне и что посетитель отправил именно номер кнопки (например, "2"). Если посетитель пришлёт номер несуществующей кнопки (например, при перечне кнопок от 1 до 8 пришлёт цифру 9) или пришлёт кнопку в любом другом виде (текст кнопки, номер вместе с текстом и т. п.), кнопка выбрана не будет и запрос не будет отправлен. Да
data.request.messageId String "fede9187f3da41c9849976a01a40d899" Идентификатор сообщения, кнопка которого была нажата. Да

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

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

Content-type: application/json

Query-string параметры: не нужны

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

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

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

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