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

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

Перед установкой Artix:TgBot необходимо добавить репозиторий Artix Loyalty Managment с помощью команд:

echo 'deb [arch=amd64] http://update.artix.su/lm/ loyalty_testing loyalty' | sudo tee /etc/apt/sources.list.d/loyalty.list
sudo aptitude update

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

aptitude install artixcs-telegram-bot

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

service artixcs-telegram-bot status

Настройка

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

По умолчанию LM_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.

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

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 = LM_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

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

Для создания 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() – возвращает неактивный баланс карты (если время начисления баллов еще не наступило).
CounterModuleМодуль для работы с сервером счетчиков

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

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

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

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

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

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