4.3.1. Инструкция как запустить бота (для работы через цифровое меню)? (на корректировке перед публикацией)

Данный бот в качестве примера реализует произвольное конфигурироемое текстовое меню на линиях. Для более быстрой реализации вашего бота рекомендуем внимательно ознакомиться с документацией к сервису.

Требования к окружению

  • OS: Linux/Windows

  • Go: 1.17+

Сборка и запуск

Сборка из исходников

./build.sh

Сборка требует установленного окружения!

Запуск собранной версии

./connect-text-bot --config=config.yml --bot=bot.yml

Где:

  • --config - путь к конфигу (путь по умолчанию - ./config/config.yml).

  • --bot - путь к конфигу бота (путь по умолчанию - ./config/bot.yml).

Данный бот отслеживает изменения конфигурации меню, содержимое можно менять “на горячую”, но стоит преварительно проверять через валидатор (например https://onlineyamltools.com/validate-yaml).

Разворачивание бота

Цифровое меню - это интерфейс в приложении 1С-Коннект, через который пользователь взаимодействует с ботом, воспроизведенном на вашем сервере.

Для корректной рыботы необходимо выполнить следующие требования и действия:

  • Подготовить машину имеющую доступ в интернет и способную принимать HTTP запросы из интернета.

    • Лучшим выбором будет Linux, возможно использование виртуальной машины

  • Настроить пользователя API в кабинете администратора 1С-Коннект:

    • Раздел Администрирование -> Настройки API

    • Создать нового пользователя.

  • Включить опцию Внешний сервер для обработки данных в нужной линии:

    • Откройте в карточку линии и в разделе Чат-бот включите соотвествующую настройку.

  • Необходимо получить ID линии для которой была включена внешняя обработка

    • Выполнит запрос https://1c-connect.atlassian.net/wiki/spaces/PUBLIC/pages/2156429313 (можно открыть ссылку https://push.1c-connect.com/v1/line/ в браузере и ввести логин/пароль от ранее созданного пользователя).

    • Найти линию в списке и сохранить ее ID.

  • На подготовленный сервер загрузить приложение бота, файл с цифровым меню.

  • Сконфигурировать и запустить приложение:

    • Создать конфигурационный файл. Пример лежит в файле config/config.yml.sample и отредактировать его.

    • Указать в блоке server адрес к серверу на котором развернут бот.

Указанный хост и порт должны быть доступны из сети Интернет.

  • Указать логин/пароль ранее созданного пользователя API.

    • Указать ID линии в разделе lines, можно указывать несколько линий.

    • Бот может отправлять файлы, в конфигурационном файле можно указать путь к папке с файлами, далее в меню указывать имена файлов для отправки в чат.

    • Приложение может быть запущено с указание путей к соответсвующим файлам.

Конфигурация меню

Конфигурационный файл представляет собой yml файл вида:

menus: start: answer: - chat: 'Здравствуйте.' buttons: - button: id: 1 text: 'a' - button: id: 2 text: 'b' - button: id: 3 text: 'nested' menu: id: 'nested_menu' answer: - chat: 'Welcome to nested menu.' buttons: - button: id: 1 text: 'get information' chat: - chat: 'information' - button: back_button: true - button: id: 4 text: 'send file' chat: - file: 'file.pdf' file_text: 'you received file!' final_menu: answer: - chat: 'Могу ли я вам чем-то еще помочь?' buttons: - button: id: 1 text: 'Да' goto: 'start' - button: id: 2 text: 'Нет' chat: - chat: 'Спасибо за обращение!' close_button: true - button: redirect_button: true back_button: id: 8 text: 'Назад' redirect_button: id: 0 text: 'Соединить со специалистом' close_button: id: 9 text: 'Закрыть обращение' error_message: 'Команда неизвестна. Попробуйте еще раз'

Директория с файлами задается параметром files_dir, в конфигурационном файле программы config.yml.

  • Конфигурация состоит из различных меню. Меню start - появляется после первого сообщения от пользователя. final_menu - резюмирует диалог.

  • Каждое меню состоит из блоков answer и buttons.

  • Блок answer отвечает за сообщение при переходе на данный раздел. При переходе между меню есть возможность отправить текст:

menus: start: answer: - chat: 'Здравствуйте.' buttons: ...

Или файл:

menus: start: answer: - file: 'file.pdf' file_text: 'Сопроводительное письмо к файлу.' buttons: ...

Или несколько сообщений и файлов:

menus: start: answer: - chat: 'Сообщение 1' - chat: 'Сообщение 2' - file: 'file1.pdf' - file: 'file2.pdf' - chat: 'Сообщение 3' buttons: ...

Также при нажатии на кнопку есть возможность отправить несколько сообщений или файлов:

menus: start: answer: - chat: 'Сообщение 1' buttons: - button: id: 1 text: 'Кнопка 1' chat: - chat: 'Сообщение 1' - chat: 'Сообщение 2' - file: 'file1.pdf' file_text: 'Сопроводительное письмо к файлу1' - file: 'file2.pdf' file_text: 'Сопроводительное письмо к файлу2' ...

Блок buttons - представляет собой список кнопок на данном уровне. У кнопки обязательно должен текст text.

buttons: - button: id: 1 text: 'Текст кнопки' # обязательное поле

Если у кнопки нет пункта goto, то после нажатия на неё будет совершен переход в final_menu.

buttons: - button: id: 1 # Нажатие на эту кнопку переведёт в final_menu text: 'Кнопка 1' - button: id: 2 # Нажатие на эту кнопку переведёт в some_menu text: 'Кнопка 2' goto: 'some_menu' # Явно указываем в какое меню переведет кнопка

Если у кнопки есть пункт menu, то после нажатия на неё будет совершен переход в подменю.

buttons: - button: id: 1 # Нажатие на эту кнопку переведёт в nested_menu text: 'Текст кнопки' chat: 'Сообщение' menu: id: 'nested_menu' ...

Настройки по умолчанию

Для специальных пунктов меню:

back_button - описывает кнопку “Назад”, которая переводит меню на уровень назад.

close_button - описывает кнопку “Закрыть обращение”, которая завершает работу с обращением.

redirect_button - описывает кнопку “Перевести на специалиста”, которая переводит работу из бот-мению на свободного
специалиста или ставит обращение в очередь, если нет свободных специалистов.

Можно задать описания по умолчанию:

back_button: id: 8 text: 'Назад' redirect_button: id: 0 text: 'Соединить со специалистом' close_button: id: 9 text: 'Закрыть обращение'

Если в конфиге отсутствует final_menu будет использовано меню по умолчанию:

final_menu: answer: - chat: 'Могу ли я вам чем-то еще помочь?' buttons: - button: id: 1 text: 'Да' goto: 'start' - button: id: 2 text: 'Нет' chat: - chat: 'Спасибо за обращение!' close_button: true - button: redirect_button: true

Если в конфиге отсутствует error_message будет использовано сообщение по умолчанию:

error_message: 'Команда неизвестна. Попробуйте еще раз'

Можно сделать сделать так, чтобы бот здоровался только один раз.

Для этого необходимо добавить следующую строчку в конфиг бота (файл bot.yml):

first_greeting: true

А также задать текст приветственного сообщения (файл bot.yml):

greeting_message: 'Здравствуйте.'

Как отправить текст:

buttons: - button: id: 1 text: 'Текст кнопки' chat: - chat: 'Сообщение'

Как отправить файл:

buttons: - button: id: 1 text: 'Текст кнопки' chat: - file: 'file.pdf' file_text: 'Сопроводительное сообщение к файлу.'

Как закрыть обращение:

buttons: - button: id: 9 text: 'Закрыть обращение' close_button: true

Как перевести обращение на специалиста:

buttons: - button: id: 0 text: 'Перевести на специалиста' redirect_button: true

Как создать меню?

Способ №1

menus: start: answer: - chat: 'Здравствуйте.' buttons: - button: id: 1 text: 'a' menu: id: 'новое_меню' answer: - chat: 'welcome' buttons: - button: id: 1 text: 'Текст кнопки' final_menu: answer: - chat: 'Могу ли я вам чем-то еще помочь?' buttons: - button: id: 1 text: 'Да' goto: 'start' - button: id: 2 text: 'Нет' chat: - chat: 'Спасибо за обращение!' close_button: true - button: redirect_button: true back_button: id: 8 text: 'Назад' redirect_button: id: 0 text: 'Соединить со специалистом' close_button: id: 9 text: 'Закрыть обращение'

Способ №2

menus: start: answer: - chat: 'Здравствуйте.' buttons: - button: id: 1 text: 'a' goto: 'новое_меню' новое_меню: answer: - chat: 'welcome' buttons: - button: id: 1 text: 'Текст кнопки' final_menu: answer: - chat: 'Могу ли я вам чем-то еще помочь?' buttons: - button: id: 1 text: 'Да' goto: 'start' - button: id: 2 text: 'Нет' chat: - chat: 'Спасибо за обращение!' close_button: true - button: redirect_button: true back_button: id: 8 text: 'Назад' redirect_button: id: 0 text: 'Соединить со специалистом' close_button: id: 9 text: 'Закрыть обращение'