Artix:TgBot является лицензируемым продуктом. Для его использования необходимо наличие лицензионного ключа. Подробнее об этом можно прочитать в разделе "Лицензирование".

С инструкцией по поэтапной установке и настройке Artix:TgBot можно ознакомиться разделе "Установка и настройка Artix Telegram Bot".

Установка Artix:TgBot

Для установки Artix:TgBot необходимо cкачать и запустить скрипт установки:

curl https://update.artix.su/static/cs/install_scripts/stable/telegram_bot/install.sh -o /tmp/install.sh
chmod +x /tmp/install.sh
/tmp/install.sh

Для проверки состояния Artix:TgBot выполните команду:

service artixcs-telegram-bot status

Обновление

Для обновления Artix:TgBot необходимо выполнить команды:

sudo apt update
sudo apt install artixcs-telegram-bot

Для обновления можно использовать скрипт установки: 

curl https://update.artix.su/static/cs/install_scripts/stable/telegram_bot/install.sh -o /tmp/install.sh
chmod +x /tmp/install.sh
/tmp/install.sh stable true

Настройка

Настройка работы Artix:TgBot осуществляется в конфигурационном файле application.properties, расположенном в директории /opt/artixcs-telegram-bot/.

НаименованиеТип данныхВозможные значениеОписаниеПримечания
server.portцелочисленный
Порт сервисаПо умолчанию 3300
su.artix.telegram.bot.tokenстроковый
Токен для подключения Telegram-бота к сторонним сервисамПо умолчанию your_token
su.artix.telegram.bot.accountingservice.prefixстроковый
URL для доступа к бонусному серверу

По умолчанию http://localhost:38054/ACC/rest/v1/

su.artix.telegram.bot.accountingservice.userстроковый
Имя пользователя для доступа к бонусному серверу

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

Необходимо указать существующий терминал на бонусном сервере

su.artix.telegram.bot.accountingservice.passwordстроковый
Пароль для доступа к бонусному серверуПо умолчанию значение не задано
su.artix.telegram.bot.csservice.prefixстроковый
URL для доступа к кассовому серверу

По умолчанию http://localhost:38051/CSrest/rest/

su.artix.telegram.bot.csservice.userстроковый
Имя пользователя для доступа к кассовому серверуПо умолчанию admin
su.artix.telegram.bot.csservice.passwordстроковый
Пароль для доступа к кассовому серверуПо умолчанию admin
su.artix.telegram.bot.salerendererservice.prefixстроковый
URL для доступа к сервису sale-rendererПо умолчанию http://localhost:38067/v1/
su.artix.telegram.bot.counter.prefixстроковый
URL для доступа к сервису счетчиков

По умолчанию http://localhost:39021

su.artix.telegram.bot.counter.userстроковый
Имя пользователя для доступа к сервису счетчиковПо умолчанию admin
su.artix.telegram.bot.counter.passwordстроковый
Пароль для доступа к сервису счетчиковПо умолчанию admin
su.artix.telegram.bot.registration.card.enableлогический
  • true
  • false
Включение регистрации новых пользователейПо умолчанию true
su.artix.telegram.bot.registration.card.lastname.fillстроковый




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

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

  • REQUIRED – обязательно к заполнению (пользователь не сможет зарегистрироваться, если поле не заполнено)
  • OPTIONAL – необязательно (заполнение поля можно пропустить)
  • DISABLE – отключено (заполнение поля не будет предложено пользователю)
su.artix.telegram.bot.registration.card.firstname.fillстроковыйТребования к заполнению поля с именем при регистрации нового пользователя
su.artix.telegram.bot.registration.card.middlenname.fillстроковыйТребования к заполнению поля с отчеством при регистрации нового пользователя
su.artix.telegram.bot.registration.card.birthday.fillстроковыйТребования к заполнению поля с датой рождения при регистрации нового пользователя
su.artix.telegram.bot.registration.card.gender.fillстроковыйТребования к заполнению поля с полом при регистрации нового пользователя
su.artix.telegram.bot.issuance.card.prefixстроковый
URL для доступа к сервису выдачи картПо умолчанию http://localhost:8094
su.artix.telegram.bot.issuance.card.userстроковый
Имя пользователя для доступа к сервису выдачи картПо умолчанию admin
su.artix.telegram.bot.issuance.card.passwordстроковый
Пароль для доступа к сервису выдачи картПо умолчанию admin
su.artix.telegram.usecase.rule.subscribeuser.cache.unitстроковый
Единица измерения времени жизни кеша для пользователей, подписанных на Telegram-ботПо умолчанию DAYS
su.artix.telegram.usecase.rule.subscribeuser.cache.durationцелочисленный
Продолжительность жизни кеша для пользователей, подписанных на Telegram-ботПо умолчанию 1
su.artix.telegram.usecase.rule.unsubscribeuser.cache.unitстроковый
Единица измерения времени жизни кеша для пользователей, заблокировавших чат с ботомПо умолчанию DAYS
su.artix.telegram.usecase.rule.unsubscribeuser.cache.durationцелочисленный
Продолжительность жизни кеша для пользователей, заблокировавших чат с ботомПо умолчанию 1
su.artix.telegram.usecase.rule.statistics.trimmer.executestartстроковый
Cron-выражение для запуска подрезки статистикиПо умолчанию 0 0 0 * * ?
su.artix.telegram.usecase.rule.statistics.trimmer.durationцелочисленный
Количество дней, за которое необходимо сохранять статистику по пользователям, которые подписались или заблокировали чат с ботомПо умолчанию 365
spring.data.mongodb.uriстроковый
Имя (URN) и адрес (URL) ресурса в сетиПо умолчанию mongodb://localhost/telegram_bot
phone_number.out_maskстроковый
Маска номера телефона

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

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

Например:

Указанный в Telegram-боте номер телефона: 89111232533.


Пример №1
Если в настройке задано значение "+7**********", то на кассовый сервер будет передаваться номер телефона в формате: "+79111232533".


Пример №2
Если в настройке задано значение "(***)-***-**-**", то на КС передается номер телефона в формате: "(911)-123-25-33".

client.age.restrict

целочисленный
Ограничение возраста клиентаПо умолчанию 18

barcode.formats

строковый
  • QRcode
  • DataMatrix
  • Code128
Форматы отображаемых кодов

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

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

card.number.mask

строковый
Маска номеров карт (макроподстановка)

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

Пример
number{cardNumber}card
Могут использоваться только латинские символы.

licencecenter.contragentId

строковый
Токен для авторизации на сервере лицензий

По умолчанию значение не задано

Настройка обязательна для заполнения.

Если настройка не задана, то чат с Telegram-ботом не запустится.

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

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

localeDirPath

строковый
Путь к сообщениям бота

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

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

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

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

Сообщения для локализации считываются из файлов в порядке приоритета: в первую очередь из основного файла MessagesBundle_Русский.properties, затем из дополнительного Sample_MessagesBundle_Русский.properties.

welcome.bonus.enable

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

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

welcome.bonus.amount

целочисленный
Количество начисляемых приветственных бонусов

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

welcome.bonus.days.active

целочисленный
Время жизни приветственных бонусов

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

welcome.bonus.acceptWeigh

целочисленный
Вес операций группы приветственных бонусов

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

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

StartCommand.buttons.client_data.enable

логический
Отображение кнопки "Профиль" в Telegram-боте

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

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

QueuePushMessage.requestsPerSecond

целочисленный
Количество сообщений, отправляемых в задаче на рассылку за одну секунду

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

Для изменения количества сообщений в файл нужно добавить настройку с необходимым значением

CleaningService.lifeDays

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

Количество дней до удаления завершенных задач из БД

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

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

Процесс удаления запускается раз в день или при перезапуске Artix:TgBot

spring.servlet.multipart.max-file-size

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

Максимальный размер файлов, принимаемых в запросах

По умолчанию 1MB

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

spring.servlet.multipart.max-request-size
целочисленный

Максимальный размер запросов

По умолчанию 10MB

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

image.barcode.width
целочисленный

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

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

image.2D_barcode.height
целочисленный

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

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

image.linear_barcode.height
целочисленный

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

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

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

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

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

Пример настройки telegram-бота
server.port=3300

su.artix.telegram.bot.token = your_token

su.artix.telegram.bot.accountingservice.prefix = http://localhost:38054/ACC/rest/v1/
su.artix.telegram.bot.accountingservice.user =  TELEGRAM_BOT_DEFAULT_TERMINAL 
su.artix.telegram.bot.accountingservice.password =

su.artix.telegram.bot.csservice.prefix = http://localhost:38051/CSrest/rest/
su.artix.telegram.bot.csservice.user = admin
su.artix.telegram.bot.csservice.password = admin

su.artix.telegram.bot.salerendererservice.prefix = http://localhost:38067/v1/

su.artix.telegram.bot.counter.prefix = http://localhost:39021
su.artix.telegram.bot.counter.user = admin
su.artix.telegram.bot.counter.password = admin

# enable registration for new users (true, false)
su.artix.telegram.bot.registration.card.enable = true
# requirements for filling out fields when registering a new user (REQUIRED, OPTIONAL, DISABLE)
su.artix.telegram.bot.registration.card.lastname.fill = REQUIRED
su.artix.telegram.bot.registration.card.firstname.fill = REQUIRED
su.artix.telegram.bot.registration.card.middlenname.fill = REQUIRED
su.artix.telegram.bot.registration.card.birthday.fill = REQUIRED
su.artix.telegram.bot.registration.card.gender.fill = REQUIRED
su.artix.telegram.bot.issuance.card.prefix = http://localhost:8094
su.artix.telegram.bot.issuance.card.user = admin
su.artix.telegram.bot.issuance.card.password = admin  

# Statistics (DAYS or MINUTES)
su.artix.telegram.usecase.rule.subscribeuser.cache.unit=DAYS
su.artix.telegram.usecase.rule.subscribeuser.cache.duration=1
su.artix.telegram.usecase.rule.unsubscribeuser.cache.unit=DAYS
su.artix.telegram.usecase.rule.unsubscribeuser.cache.duration=1
su.artix.telegram.usecase.rule.statistics.trimmer.executestart=0 0 0 * * ?
su.artix.telegram.usecase.rule.statistics.trimmer.duration=365

spring.data.mongodb.uri = mongodb://localhost/telegram_bot
phone_number.out_mask = 7**********
client.age.restrict = 18

#Форматы отображаемых кодов. Поддерживаемые форматы: QRCode,DataMatrix,Code128
barcode.formats=QRcode, DataMatrix, Code128

card.number.mask={cardNumber}

# токен для авторизации на сервере лицензий
licencecenter.contragentId =

serviceName=artixcs-telegram-bot

localeDirPath=/opt/artixcs-telegram-bot/locale

# welcome bonus
welcome.bonus.enable=false
welcome.bonus.amount=1000
welcome.bonus.days.active=7
welcome.bonus.acceptWeight=300

Создание бота

Для создания Telegram-бота необходимо:

  1. В приложении Telegram найти и запустить бота @BotFather.
  2. Выбрать команду /newbot и задать имя для будущего бота.
  3. Токен, полученный от бота @BotFather, указать в настройке su.artix.telegram.bot.token в конфигурационном файле /opt/artixcs-telegram-bot/application.properties.

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

    systemctl restart artixcs-telegram-bot
Для начала работы необходимо в приложении Telegram найти бота по имени и запустить.

Использование SpEL-выражения в файле с сообщениями от Telegram-бота

Для переноса строки необходимо использовать символ "\".

Для использования SpEL-выражения в файле с сообщениями от Telegram-бота, который хранится в директории /opt/artixcs-telegram-bot/locale, необходимо прописать выражение в фигурных скобках, поставив перед ними знак $:

${IT_IS_SPEL}

Модули для использования в 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Не забудьте заполнить профиль, чтобы открыть переход на следующий уровень'}

На экране будет отображено:

Пример 2
title_menu = Добро пожаловать\n\
             Накоплено ${#BonusModule.balance()} бонусных баллов\n\
             ${#BonusModule.expiringBalance().amountBurn() == 0 ? '' :\
             'Успейте потратить бонусы: '.concat(#BonusModule.expiringBalance().amountBurn().movePointLeft(2)).concat(' до ').concat(new java.text.SimpleDateFormat("dd MMMM", T(java.util.Locale).of("ru")).format(#BonusModule.expiringBalance().dateEnd()))}\n\

На экране будет отображено:

Уточнения по работе с Telegram-ботом

  • При ошибках валидации лицензии сервис Artix:TgBot продолжает работу, но все операции в чате с Telegram-ботом будут недоступны.
  • Сессия создается сразу же, как только пользователь отправил сообщение в чат, и прерывается после 5-ти минут бездействия или при перезапуске бота.
  • Измененные данные из раздела "Профиль" поступают на кассовый сервер каждые 10 секунд. Если в течение 10-ти секунд пользователь отправит несколько запросов на изменение, то все они будут отправлены на кассовый сервер как один запрос.
  • В один момент времени пользователем может быть выполнена только одна задача. Например, если пользователь запросил список покупок и, не дожидаясь ответа, запросил список акций, то второй запрос выполнен не будет.
  • No labels