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 автоматически назначаются все онлайн-чаты, которые поступают в отдел, в который этот робот добавлен.

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

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

Настройка

Инструкция по настройке и подключению умного бота актуальна для сервиса 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": (текстовое описание ошибки)
}

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

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

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

URL: /api/bot/v2/send_message

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

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

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

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

Поле Тип Описание
message Json Сообщение.
chat_id Integer Идентификатор чата.

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

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

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

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

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

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

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

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

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

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

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

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

Поле Тип Пример Описание
kind String "file_operator" Тип сообщения. В данном случае это сообщения оператора, содержащие отправленные файлы и т. д. Все типы сообщений в этой статье.
data.url String "https://somesite.com/img54-65-79.jpg" URL-адрес файла.
data.name String "image.png" Имя файла.
Имя должно содержать расширение.
data.media_type String "pdf" Internet Media Type.

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

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

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

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

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

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

Поле Тип Описание
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 не был найден, либо чат не назначен на робота, либо диалог неактивен (потому что был закрыт, переведен в общую очередь и др.)

Перевод чата

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

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

Запрос:

{
    "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" Переводить ли чат на отдел, если в нем нет операторов онлайн. По умолчанию true. Нет

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

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

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

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

Запрос:

{
    "chat_id":462
}

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

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

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

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

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

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

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

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

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

Для этих запросов авторизация не требуется.
Для повышения безопасности в URL можно добавить секретный ключ, сгенерированный после добавления бота через Консоль управления. Пройдите процесс создания бота согласно пункту Настройка. После сохранения бота скопируйте ключ в поле Токен авторизации.

Данный ключ вставляется в URL следующим образом: вместо address указывается address/secret_key, где secret_key – токен, полученный после создания бота из поля Токен авторизации.

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

В случае успеха со стороны Webim будет дан следующий ответ:
200 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"
        }
    }
}

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

Поле Тип Пример Описание
event String "new_chat" Тип события.
chat_id Integer "247" Идентификатор чата.
visitor_id String "03e1c040d8214bfa8ccfbb053186a24a" Идентификатор посетителя.
visitor.fields Json "{"name": "Владислав", "phone": "+79113258746", ...} Известная информация о посетителе в виде пар ключ-значение. Все поля можно посмотреть здесь.

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

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

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

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

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

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

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

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

{
    "id":"c3e19d57f64e43c3afabdef2ef4e4054",
    "kind":"file_visitor",
    "data":{
        "id":"81f0488",
        "name":"file.txt",
        "media_type":"text",
        "size":1650
    }
} 

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

Поле Тип Пример Описание
id String "6355ba4163f947b9b77f7e65ce4317a7" Идентификатор сообщения.
kind String "file_visitor" Тип сообщения. Все типы сообщений в этой статье.
data.id String "81f0488" Идентификатор файла.
data.name String "somefile.pdf" Название файла
data.media_type String "application" Internet Media Type.
data.size Integer "12350" Размер файла в байтах.

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

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

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

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