Artix:MAX Bot является лицензируемым продуктом. Подробнее об этом можно прочитать в разделе "Лицензирование Artix:MAX Bot".
Установка
Для использования Artix:MAX Bot может потребоваться установка artixcs-issuance-card – для создания виртуальных карт клиентов.
Для установки необходимо cкачать и запустить скрипт установки:
curl https://update.artix.su/static/cs/install_scripts/stable/max_bot/install.sh -o /tmp/max.sh chmod +x /tmp/max.sh /tmp/max.sh
Для проверки состояния выполните команду:
systemctl status artixcs-max-bot
Обновление
Для обновления Artix:MAX Bot необходимо выполнить команды:
sudo apt update sudo apt install artixcs-max-bot
Для обновления можно использовать скрипт установки:
curl https://update.artix.su/static/cs/install_scripts/stable/max_bot/install.sh -o /tmp/max.sh chmod +x /tmp/max.sh /tmp/max.sh stable true
Настройка
Настройка работы Artix:Max Bot осуществляется в конфигурационном файле application.properties, расположенном в директории /opt/artixcs-max-bot/.
| Наименование | Тип данных | Возможные значение | Описание | Примечания |
|---|---|---|---|---|
| server.servlet.context-path | строковый | Контекстный путь для подключения к MAX | По умолчанию /max-bot | |
| server.port | целочисленный | Порт сервиса | По умолчанию 8055 | |
| mongo.database.uri | строковый | Имя (URN) и адрес (URL) ресурса в сети | По умолчанию mongodb://localhost/max_bot | |
| max.bot.token | строковый | Токен для подключения MAX-бота к сторонним сервисам | По умолчанию your_token | |
| max.bot.api.base.url | строковый | Подключение к API сервиса MAX | По умолчанию https://platform-api2.max.ru | |
| max.bot.phone.number.out.mask | строковый | Маска номера телефона | По умолчанию + Согласно заданному в настройке значению осуществляется поиск клиента в базе данных Например: Указанный в MAX-боте номер телефона: 89111232533. Пример №1
Если в настройке задано значение "+7**********", то на кассовый сервер будет передаваться номер телефона в формате: " +79111232533".
Пример №2
Если в настройке задано значение "(***)-***-**-**", то на КС передается номер телефона в формате: " (911)-123-25-33".
| |
| max.bot.cs.service.url | строковый | URL для доступа к кассовому серверу | По умолчанию http://localhost:38051/CSrest/rest/ | |
| max.bot.cs.service.user | строковый | Имя пользователя для доступа к кассовому серверу | По умолчанию admin | |
| max.bot.cs.service.password | строковый | Пароль для доступа к кассовому серверу | По умолчанию admin | |
| max.bot.cs.client.update.queue.fixed.rate | целочисленный | Периодичность обработки очереди обновлений данных между клиентом и кассовым сервером (в милисекундах) | По умолчанию 10000 | |
| max.bot.accounting.admin.service.url | строковый | URL для доступа к бонусному серверу для начисления приветственных бонусов | По умолчанию http://localhost:38054/ACC/rest/admin/terminal/ | |
| max.bot.accounting.service.url | строковый | URL для доступа к бонусному серверу | По умолчанию | |
| max.bot.accounting.service.user | строковый | Имя пользователя для доступа к бонусному серверу | По умолчанию Необходимо указать существующий терминал на бонусном сервере | |
| max.bot.accounting.service.password | строковый | Пароль для доступа к бонусному серверу | По умолчанию значение не задано | |
| max.bot.accounting.service.get.expiring.balance | логический |
| Получать информацию о сгорающих в ближайшее время бонусных баллах | По умолчанию true |
| max.bot.accounting.service.days.from.now.to.count.bonus.expiring | целочисленный | Количество дней от текущей даты для подсчета сгорающих бонусов | По умолчанию 7 | |
| max.bot.issuance.card.url | строковый | URL для доступа к сервису выдачи карт | По умолчанию http://localhost:8094 | |
| max.bot.issuance.card.user | строковый | Имя пользователя для доступа к сервису выдачи карт | По умолчанию admin | |
| max.bot.issuance.card.password | строковый | Пароль для доступа к сервису выдачи карт | По умолчанию admin | |
| max.bot.issuance.card.queue.fixed.rate | целочисленный | Период, в течение которого расписание управляет очередью на регистрацию карты в сервисе выдачи карт (в милисекундах) | По умолчанию 60000 | |
| max.bot.counter.url | строковый | URL для доступа к сервису счетчиков | По умолчанию http://localhost:39021 | |
| max.bot.counter.user | строковый | Имя пользователя для доступа к сервису счетчиков | По умолчанию admin | |
| max.bot.counter.password | строковый | Пароль для доступа к сервису счетчиков | По умолчанию admin | |
max.bot.welcome.bonus.enable | логический |
| Включение начисление приветственных бонусов | По умолчанию |
max.bot.welcome.bonus.amount | целочисленный | Количество начисляемых приветственных бонусов при регистрации в MAX-боте | По умолчанию 1000 | |
max.bot.welcome.bonus.days.active | целочисленный | Время жизни приветственных бонусов (в днях) | По умолчанию 7 | |
max.bot.welcome.bonus.acceptWeight | целочисленный | Вес операций группы приветственных бонусов | По умолчанию 300 | |
| max.bot.registration.card.lastname | строковый |
| Требования к заполнению поля с фамилией при регистрации нового пользователя | По умолчанию
|
| max.bot.registration.card.firstname | строковый | Требования к заполнению поля с именем при регистрации нового пользователя | ||
| max.bot.registration.card.middlename | строковый | Требования к заполнению поля с отчеством при регистрации нового пользователя | ||
| max.bot.registration.card.birthday | строковый | Требования к заполнению поля с датой рождения при регистрации нового пользователя | ||
max.bot.registration.card.gender | строковый | Требования к заполнению поля с полом при регистрации нового пользователя | ||
max.bot.local.dir.path | строковый | Каталог с файлами локализации | По умолчанию Путь до файлов, в которых хранятся сообщения от бота В директории по умолчанию хранится файл Дополнительно в директории хранится файл Сообщения для локализации считываются из файлов в порядке приоритета: в первую очередь из основного файла MessagesBundle_ru.properties, затем из дополнительного Sample_MessagesBundle_ru.properties. | |
| max.botcard.number.mask | строковый | Маска номеров карт (макроподстановка) | По умолчанию Могут использоваться только латинские символы Пример
number{cardNumber}card
| |
| max.bot.barcode.formats | строковый |
| Форматы отображаемых кодов | Настройка необходима для отображения в меню кнопки "Показать карту" Если в настройке не указан ни один из форматов, то кнопка "Показать карту" не будет отображена |
| max.bot.profile.visible | логический |
| Отображение кнопки профиля в главном меню | По умолчанию |
| max.bot.client.unsubscribe.allowed | логический |
| Отображение кнопки подписки/отписки от рассылки | По умолчанию Параметр предназначен для управления подпиской на рассылки: отписки от других каналов рассылки (например, SMS) или подписки на рассылки при наличии доступного разрешенного канала. Мессенджер MAX не поддерживает возможность рассылки сообщений. |
| max.bot.client.age.restrict | целочисленный | Минимальный возраст клиента | По умолчанию | |
| max.bot.licence.file | строковый | Путь до файла лицензии | По умолчанию | |
| serviceName | строковый | Наименование сервиса | По умолчанию | |
Скрытые настройки | ||||
| max.bot.image.barcode.frame.size | целочисленный | Размер дополнительный рамки вокруг изображения с кодом (в пикселях) | По умолчанию | |
max.bot.image.barcode.width | целочисленный | Ширина генерируемых кодов (в пикселях) | По умолчанию | |
max.bot.image.2D_barcode.height | целочисленный | Высота генерируемых двумерных кодов (в пикселях) | По умолчанию | |
max.bot.image.linear_barcode.height | целочисленный | Высота генерируемых линейных кодов (в пикселях) | По умолчанию | |
server.servlet.context-path=/max-bot
server.port=8055
mongo.database.uri=mongodb://localhost/max_bot
max.bot.token=your_token
max.bot.api.base.url=https://platform-api2.max.ru
max.bot.phone.number.out.mask=+7**********
max.bot.cs.service.url=http://localhost:38051/CSrest/rest/
max.bot.cs.service.user=admin
max.bot.cs.service.password=admin
max.bot.cs.client.update.queue.fixed.rate=10000
max.bot.accounting.admin.service.url=http://localhost:38054/ACC/rest/admin/terminal/
max.bot.accounting.service.url=http://localhost:38054/ACC/rest/v1/
max.bot.accounting.service.user=TELEGRAM_BOT_DEFAULT_TERMINAL
max.bot.accounting.service.password=
max.bot.accounting.service.get.expiring.balance=true
max.bot.accounting.service.days.from.now.to.count.bonus.expiring=7
max.bot.issuance.card.url=http://localhost:8094
max.bot.issuance.card.user=admin
max.bot.issuance.card.password=admin
max.bot.issuance.card.queue.fixed.rate=60000
max.bot.counter.url = http://localhost:39021
max.bot.counter.user = admin
max.bot.counter.password = admin
# welcome bonus
max.bot.welcome.bonus.enable=false
max.bot.welcome.bonus.amount=1000
max.bot.welcome.bonus.days.active=7
max.bot.welcome.bonus.acceptWeight=300
# requirements for filling out fields when registering a new user (REQUIRED, OPTIONAL, DISABLE)
max.bot.registration.lastname=REQUIRED
max.bot.registration.firstname=REQUIRED
max.bot.registration.middlename=REQUIRED
max.bot.registration.birthday=REQUIRED
max.bot.registration.gender=REQUIRED
# Блок определения режима работы LongPolling/WebHooks (по умолчанию WebHooks)
max.bot.webhook.enabled=true
max.bot.webhook.public-url=
max.bot.webhook.path=/webhook
max.bot.webhook.port=8099
max.bot.webhook.secret=
# Каталог с файлами локализации
max.bot.local.dir.path=/opt/artixcs-max-bot/locale
# Настройки карты пользователя
max.botcard.number.mask={cardNumber}
max.bot.barcode.formats=QRCode
# Отображение кнопки профиля в главном меню
max.bot.profile.visible=true
max.bot.client.unsubscribe.allowed=false
# Минимальный возраст клиента
max.bot.client.age.restrict=18
# Лицензирование
max.bot.licence.file=/opt/artixcs-max-bot/licence
serviceName=artixcs-max-bot
Создание бота
Подробнее о создании бота можно прочитать в документации MAX.
Для создания бота в мессенджере MAX необходимо:
В приложении
MAXоткрыть платформу MAX для партнёров.Перейти в раздел "Чат-боты" и нажать "Создать".
Заполнить данные бота и нажать "Создать".
После прохождения модерации получить токен бота и указать его в настройке
max.bot.tokenв конфигурационном файле/opt/artixcs-max-bot/application.properties.Перезапустить Artix:Max Bot командой:
systemctl restart artixcs-max-bot
Для начала работы необходимо в приложении MAX найти бота по имени и запустить.
Настройка Webhook
Для работы бота через Webhook необходимо указать публичный URL сервера, доступный для запросов от MAX.
Настройки Webhook задаются в конфигурационном файле application.properties, расположенном в директории /opt/artixcs-max-bot/.
| Наименование | Тип данных | Возможные значение | Описание | Примечания |
|---|---|---|---|---|
| max.bot.webhook.enabled | логический |
| Включение Webhook | По умолчанию |
| max.bot.webhook.public-url | строковый | Публичный URL сервера, доступный для MAX | ||
| max.bot.webhook.path | строковый | Путь для получения событий от MAX | По умолчанию /webhook | |
| max.bot.webhook.port | целочисленный | Порт http-сервера | По умолчанию 8099 | |
| max.bot.webhook.secret | строковый | Секретный ключ для проверки запросов Webhook | Длина от 5 до 256 символов. Допускаются латинские буквы, цифры и дефис |
Проверка подлинности запросов
Параметр max.bot.webhook.secret – общий секрет сервера MAX и бота, используемый для проверки подлинности входящих запросов Webhook.
В качестве значения задается произвольная строка длиной от 5 до 256 символов. Допускаются латинские буквы (A–Z, a–z), цифры (0–9) и дефис (–). Рекомендуется использовать случайную строку, например из 64 шестнадцатеричных символов.
При запуске бот передает секрет в поле secret запроса POST /subscriptions. При отправке события MAX добавляет значение секрета в заголовок X-Max-Bot-Api-Secret каждого запроса Webhook.
При получении запроса MaxWebhookServer проверяет значение заголовка:
- если заголовок отсутствует или его значение не совпадает с настроенным секретом, то сервер возвращает ответ
401 Unauthorized, не выполняя обработку события, - если параметр max.bot.webhook.secret не задан, то проверка заголовка отключается.
Использование секрета рекомендуется для проверки подлинности запросов и ограничения обработки событий, поступающих от MAX.
Переход с Webhook на LongPolling
Для перехода на LongPolling недостаточно установить для параметра max.bot.webhook.enabled значение false. Зарегистрированный в MAX Webhook необходимо удалить вручную.
Для перехода с Webhook на LongPolling необходимо:
В конфигурационном файле
/opt/artixcs-max-bot/application.propertiesустановить значение:max.bot.webhook.enabled=false
Перезапустить Artix:MaxBot командой:
systemctl restart artixcs-max-bot
Получить список зарегистрированных Webhook, используя команду:
curl -k -X GET "https://platform-api2.max.ru/subscriptions" -H "Authorization: <токен_бота>"
В ответе найти URL зарегистрированного Webhook и удалить его запросом:
curl -k -X DELETE "https://platform-api2.max.ru/subscriptions?url=<URL_Webhook>" -H "Authorization: <токен_бота>"
Использование SpEL-выражения в файле с сообщениями
Для использования SpEL-выражения в файле с сообщениями от бота необходимо прописать выражение в фигурных скобках, поставив перед ними знак $:
${IT_IS_SPEL}
Файлы сообщений от бота хранятся в директории /opt/artixcs-max-bot/locale.
Модули для использования в SpEL-выражении:
| Наименование модуля | Описание | Примечания |
|---|---|---|
| BonusModule | Модуль для работы с сервером бонусов | Поддержаны следующие методы:
|
| CounterModule | Модуль для работы с сервером счетчиков | Поддержаны следующие методы:
|
| ClientModule | Модуль для работы с данными клиента | Поддержаны следующие методы:
|
Порядок обращения модулей определяется последовательностью их использования в SpEL-выражении. Используемые модули привязываются к клиенту, выполняющему запрос.
Помимо указанных модулей в SpEL-выражениях используются нативные конструкции языка Java.
title_menu = Добро пожаловать\n\
Накопленно ${#BonusModule.balance()} бонусных баллов\n\
Ожидается к начислению ${#BonusModule.inactiveBalance()} бонусных баллов\n\
Оплачивайте бонусами до 30% от стоимости покупки\n\
Ваш уровень: ${(#CounterModule.sumCounter('counterID').compareTo(new java.math.BigDecimal('10000.00')) < 0 || #ClientModule.emailConfirmed() != true) ? 'Начальный' : (#CounterModule.sumCounter('counterID').compareTo(new java.math.BigDecimal('30000.00')) < 0 ? 'Средний' : 'Высокий')}\n\
Начисление с каждой покупки: ${(#CounterModule.sumCounter('counterID').compareTo(new java.math.BigDecimal('10000.00')) < 0 || #ClientModule.emailConfirmed() != true) ? '5%' : (#CounterModule.sumCounter('counterID').compareTo(new java.math.BigDecimal('30000.00')) < 0 ? '7%' : '10%')}\
${#ClientModule.emailConfirmed() != true ? '' : 10000.00-#CounterModule.sumCounter('counterID') > 0 ? '\nДо следующего уровня осталось: ' + (10000.00-#CounterModule.sumCounter('counterID') + ' рублей') : 30000.00-#CounterModule.sumCounter('counterID') > 0 ? '\nДо следующего уровня осталось: ' + (30000.00-#CounterModule.sumCounter('counterID') + ' рублей') : '\nВы на максимальном уровне'}\
${#ClientModule.isProfileComplete() ? '' : '\nНе забудьте заполнить профиль, чтобы открыть переход на следующий уровень'}\nEmail подтвержден: ${#ClientModule.emailConfirmed()}\nПрофиль заполнен: ${#ClientModule.isProfileComplete()}
На экране будет отображено:
Уточнение по работе с MAX-ботом
При начале выполнении операции проверяется, свободна ли сессия чата. Сессия считается занятой, если для текущего чата уже выполняется другая операция, например регистрация или редактирование профиля.
Если сессия свободна, то данные для выполнения операции сохраняются в кэше по идентификатору чата клиента. После создания сессии пользователю предоставляется 5 минут на ввод данных. Если за это время пользователь не завершает операцию, то сессия и связанные с ней данные удаляются. После завершения операции сессия освобождается. При перезапуске приложения все сессии удаляются.
Логирование работы
Логирование работы сервиса ведется в файле /var/log/artix/artixcs-max-bot/artixcs-max-bot.log.
