Extbot

Extbot — пример чат-бота для Webim. Extbot не подойдёт для общения с реальными посетителями, но сможет продемонстрировать возможности платформы. Бот представляет из себя программу, которая запускается на отдельном компьютере и подключается к Webim через External Bot API.

Extbot умеет:

• Отправлять текст
• Отправлять файлы
• Отправлять кнопки
• Переводить диалог на оператора
• Переводить диалог на отдел
• Переводить диалог в очередь
• Закрывать диалог

Установка бота

Понадобится Python 3.8+ и pip.

Установить бота можно командой:

pip install "https://github.com/webim/webim-extbot/archive/refs/heads/main.zip"

Чтобы проверить, что бот установлен, можно посмотреть его справку:

extbot --help

Или, если команда extbot не определяется:

python -m extbot --help

Периодически стоит повторять команду установки, чтобы установить последние обновления бота.

Запуск бота

Когда бот успешно установлен, его можно запустить. Например:

extbot --domain demo.webim.ru --token my-secret-token

Команда запускает бота и выводит ссылку на его API. Для работы API 2.0 в команду необходимо передать параметр --domain с доменным именем, на котором доступен Webim, а также параметр --token с токеном бота из настроек Webim, см. "Подключение бота к Webim" ниже. Больше настроек запуска в справке extbot --help.

Для подключения к Webim бот должен быть доступен через публичный IP адрес. Если при запуске локально такой возможности нет, то можно воспользоваться такими сервисами, как ngrok или Cloudflare Tunnel.

К примеру, по-умолчанию бот запускается на localhost:8000. Тогда можно запустить ngrok:

ngrok http 8000

И бот будет доступен по ссылке "Forwarding" из экрана ngrok до тех пор, пока ngrok запущен.

Подключение бота к Webim

В интерфейсе Webim потребуется настроить бота в соответствии с инструкциями. В поле "Ссылка на внешний API" указывается URL, по которому доступен Extbot, например тот, который получен через ngrok.

Дополнительные возможности

Перевод диалога на оператора

При использовании API 2.0 в меню бота можно добавить кнопку, по нажатию на которую диалог будет переводиться на заданного оператора. Для этого необходимо при запуске бота передать ID нужного оператора в опции --agent-id:

extbot --domain demo.webim.ru --token my-secret-token --agent-id 240001

Найти ID оператора можно в Webim в разделе "Сотрудники". А в более старых релизах Webim — в адресной строке браузера, перейдя из раздела "Сотрудники" в настройки нужного сотрудника.

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

Также в API 2.0 в меню бота можно добавить кнопку, по нажатию на которую диалог будет переводиться в заданный отдел. Для этого необходимо передать буквенный идентификатор нужного отдела в опции --dep-key:

extbot --domain demo.webim.ru --token my-secret-token --dep-key my_department

Найти буквенный идентификатор можно в соответствующем поле в настройках отдела в Webim.

Перевод диалога в очередь

За исключением редких случаев в меню бота отображается кнопка для перевода диалога в очередь — очередь текущего отдела, если для диалога выбран отдел, или общую очередь, если диалог без отдела. В случае Bot API 2.0 кнопка не отображается, если используется Webim версии старше, чем 10.4, так как в старых версиях возможность перевода в очередь в Bot API 2.0 не предусмотрена.

Произвольная кнопка

В меню бота можно добавить дополнительную кнопку, текст которой и текст ответа бота на которую задаются опциями --custom-button и --custom-button-response соответственно.

extbot --custom-button Ping --custom-button-response Pong

Если одна из этих двух опций отсутствует, то для неё будет использован текст по умолчанию. Если отсутствуют обе, то произвольной кнопки в меню не будет.

Реакции на файловые сообщения

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

Логи внутренней работы бота

Бота можно запустить с опцией --verbose, тогда он будет выводить более подробную информацию о своей работе, в том числе данные, которыми обменивается с Webim. Обычно бота лучше запускать без этой опции, чтобы среди внутренних сообщений не затерялись более важные, например сообщения об ошибках.

Работа с разными версиями External Bot API

Помимо External Bot API 2.0, Extbot может работать через устаревшую версию External Bot API 1.0. Когда Extbot получает HTTP-запрос со стороны Webim, он определяет используемую версию API по заголовку X-Bot-API-Version, который появился в Webim 10.3. Для более старых или нестандартных релизов в настройках бота в Webim в поле "Ссылка на внешний API" нужно добавить суффикс /v2 или /v1, который подскажет Extbot, какая версия API используется.

Удаление бота

При необходимости бота можно удалить командой:

pip uninstall extbot

Журнал изменений

См. CHANGELOG.md

Участие в разработке бота

См. CONTRIBUTING.md