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строковый
Маска номера телефона

По умолчанию +7**********

Согласно заданному в настройке значению осуществляется поиск клиента в базе данных

Например:

Указанный в 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 для доступа к бонусному серверу

По умолчанию 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
  • false
Получать информацию о сгорающих в ближайшее время бонусных баллахПо умолчанию 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

логический
  • true
  • false
Включение начисление приветственных бонусов 

По умолчанию false

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строковый




  • REQUIRED
  • OPTIONAL
  • DISABLE
Требования к заполнению поля с фамилией при регистрации нового пользователя

По умолчанию REQUIRED

  • REQUIRED – обязательно к заполнению (пользователь не сможет зарегистрироваться, если поле не заполнено)
  • OPTIONAL – необязательно (заполнение поля можно пропустить)
  • DISABLE – отключено (заполнение поля не будет предложено пользователю)
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

строковый
Каталог с файлами локализации

По умолчанию /opt/artixcs-max-bot/locale

Путь до файлов, в которых хранятся сообщения от бота

В директории по умолчанию хранится файл MessagesBundle_ru.properties, при необходимости в нем можно исправить текст в сообщениях и кнопках бота, после обновления MAX-бота сообщения в данном файле не перезаписываются.

Дополнительно в директории хранится файл Sample_MessagesBundle_ru.properties, в котором содержатся все актуальные сообщения, после каждого обновления Artix:Max Bot сообщения перезаписываются.

Сообщения для локализации считываются из файлов в порядке приоритета: в первую очередь из основного файла MessagesBundle_ru.properties, затем из дополнительного Sample_MessagesBundle_ru.properties.
max.botcard.number.maskстроковый
Маска номеров карт (макроподстановка)

По умолчанию {cardNumber}.

Могут использоваться только латинские символы

Пример
number{cardNumber}card
max.bot.barcode.formatsстроковый
  • QRcode
  • DataMatrix
  • Code128
Форматы отображаемых кодов

Настройка необходима для отображения в меню кнопки "Показать карту"

Если в настройке не указан ни один из форматов, то кнопка "Показать карту" не будет отображена

max.bot.profile.visibleлогический
  • true
  • false
Отображение кнопки профиля в главном меню

По умолчанию true

max.bot.client.unsubscribe.allowedлогический
  • true
  • false
Отображение кнопки подписки/отписки от рассылки

По умолчанию false

Параметр предназначен для управления подпиской на рассылки: отписки от других каналов рассылки (например, SMS) или подписки на рассылки при наличии доступного разрешенного канала. Мессенджер MAX не поддерживает возможность рассылки сообщений.

max.bot.client.age.restrictцелочисленный
Минимальный возраст клиента

По умолчанию 18

max.bot.licence.fileстроковый
Путь до файла лицензии

По умолчанию /opt/artixcs-max-bot/licence

serviceNameстроковый
Наименование сервиса

По умолчанию artixcs-max-bot

Скрытые настройки

max.bot.image.barcode.frame.sizeцелочисленный

Размер дополнительный рамки вокруг изображения с кодом (в пикселях)

По умолчанию 20

max.bot.image.barcode.width

целочисленный

Ширина генерируемых кодов (в пикселях)

По умолчанию 400

max.bot.image.2D_barcode.height

целочисленный

Высота генерируемых двумерных кодов (в пикселях)

По умолчанию 400

max.bot.image.linear_barcode.height

целочисленный

Высота генерируемых линейных кодов (в пикселях)

По умолчанию 150

Пример настройки
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 необходимо:

  1. В приложении MAX открыть платформу MAX для партнёров.

  2. Перейти в раздел "Чат-боты" и нажать "Создать".

  3. Заполнить данные бота и нажать "Создать".

  4. После прохождения модерации получить токен бота и указать его в настройке max.bot.token в конфигурационном файле /opt/artixcs-max-bot/application.properties.

  5. Перезапустить Artix:Max Bot командой:

    systemctl restart artixcs-max-bot

Для начала работы необходимо в приложении MAX найти бота по имени и запустить.

Настройка Webhook

Для работы бота через Webhook необходимо указать публичный URL сервера, доступный для запросов от MAX.

Настройки Webhook задаются в конфигурационном файле application.properties, расположенном в директории /opt/artixcs-max-bot/.

НаименованиеТип данныхВозможные значениеОписаниеПримечания
max.bot.webhook.enabledлогический
  • true
  • false
Включение Webhook

По умолчанию true

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 необходимо:

  1. В конфигурационном файле /opt/artixcs-max-bot/application.properties установить значение:

    max.bot.webhook.enabled=false
  2. Перезапустить Artix:MaxBot командой:

    systemctl restart artixcs-max-bot
  3. Получить список зарегистрированных Webhook, используя команду:

    curl -k -X GET "https://platform-api2.max.ru/subscriptions" -H "Authorization: <токен_бота>" 
  4. В ответе найти 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Модуль для работы с сервером бонусов

Поддержаны следующие методы:

  • balance() – возвращает активный баланс карты,
  • inactiveBalance() – возвращает неактивный баланс карты (если время начисления баллов еще не наступило),
  • expiringBalance() – возвращает сгорающие баллы:

    • amountBurn() – возвращает количество сгорающих баллов,
    • dateEnd() – возвращает дату сгорания бонусных баллов.
CounterModuleМодуль для работы с сервером счетчиков

Поддержаны следующие методы:

  • calcSumCountersByName (counterName) – возвращает активные накопления на счетчиках по наименованию,
  • sumCounter (idCounter) – возвращает активные накопления на счетчиках по идентификатору счетчика.
ClientModuleМодуль для работы с данными клиента

Поддержаны следующие методы:

  • emailConfirmed() – возвращает true, если почта клиента подтверждена,
  • getExtendedClient() – возвращает информацию о клиенте,
  • isProfileComplete() – возвращает true если у клиента заполнены "Имя", "Почта" и "Дата рождения".

Порядок обращения модулей определяется последовательностью их использования в SpEL-выражении. Используемые модули привязываются к клиенту, выполняющему запрос.

Помимо указанных модулей в SpEL-выражениях используются нативные конструкции языка Java.

Примеры использования SpEL-выражений в приветственном сообщении
Пример 1
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.

  • No labels