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: 'Закрыть обращение'