ClapTrapBot - це інтерактивний телеграм-бот, який надає абонентам швидкий доступ до основних можливостей кабінету користувача без необхідності відкривати його в браузері. Через бот користувач може переглядати свій профіль, баланс, історію платежів, робити онлайн-оплати, користуватись кредитом, отримувати сповіщення та звертатися до служби підтримки.

Бот особливо зручний для тих, хто користується смартфоном: усі дії виконуються просто у чаті - без паролів, авторизацій і зайвих переходів.

У випадку, якщо в вас ще немає бота який ви будете використовувати в ролі користувацького бота, для взаємодії з користувачами, можете скористатись наступним посібником і створити собі якогось новенького для цього.

Важливо: не використовуйте, як кабінетного користувацького бота, токен вже існуючого, і прописаного в вас в Собаці-посилаці, що вже використовується для розсилок вашому персоналу! Використовуйте інший токен іншого бота для цього. Це інша сутність!

Для роботи ClaptrapBot, в силу своєї інтерактивності, використовує веб хуки. Їх реалізовано для нього в модулі claptrapbot. Тобто базовим посиланням є не що інше ніж

https://yourhost.com/billing/?module=claptrapbot

Відповідна опція конфігу, вказує на необхідність додаткової авторизації, за допомогою GET параметру auth. Ось так:

alter.ini

CLAPTRAPBOT_AUTH_STRING="changeme"

Відповідно, повна валідна URL веб хука вашого бота буде в цьому випадку виглядати наступним чином:

https://yourhost.com/billing/?module=claptrapbot&auth=changeme

Важливо: очевидно, що від вас очікується той факт, що ви зміните значення опції CLAPTRAPBOT_AUTH_STRING на якийсь свій рандомний рядок тексту. Не використовуйте для цього токен боту. Просто якийсь інший рандом. Якщо складно придумати - впадіть обличчям на клавіатуру. Так, ви можете залишити опцію порожньою, і використовувати хук взагалі без авторизації, але “щоби що?”.

Варто також помітити, що Telegram дозволяє використовувати як веб-хуки, тільки https посилання. І так, тільки на портах 443, 80, 88, 8443. Також очевидно, що якщо ви не знехтували нашими рекомендаціями що до безпеки доступ до адміністративного інтерфейсу білінгу, у вас повинен би бути обмеженим ззовні. Щоб не гратись і не дозволяти доступ поштучно, для Telegram до цілої адмінки, ви можете, прокинути посилання на ваш вебхук в якусь іншу URL засобами вашого веб сервера, ну скажімо якось так, або ж скористатись мінімалістичним web-proxy, наприклад tgtinygate aka TGTG, спеціально зробленим під ці задачі. Також ніхто вас не зобов'язує тримати його прямо на білінговому сервері. Наприклад, ваш Ubilling знаходиться на хості з сірою IP адресою, десь за NAT-ом, або до нього дропаються всі звернення окрім як від вашої внутрішньої інфраструктури. В цьому випадку, ви можете, розмітити TGTG на будь-якому хості, з працюючим https, доступному ззовні:

# cd /usr/local/www/apache24/data/
# mkdir tgtinygate_changeme
# cd tgtinygate_changeme
# fetch https://raw.githubusercontent.com/nightflyza/tgtinygate/refs/heads/main/index.php

Важливо: З міркувань безпеки використовуйте випадкове ім'я директорії замість tgtinygate_changeme. Ім'я директорії стає частиною URL-адреси вашого веб-хука, тому використання випадкового імені ускладнює зловмисникам вгадування вашого ендпоінта. Приклад: tgtinygate_a7b19c2d4e1f3 або щось типу tgtg_9W8k2m5p7q. Не використовуйте в ролі рандому частину вашого токена!

після чого, налаштувати його якось так:

$botHookUrl = 'http://yourhiddenhost.com/billing/?module=claptrapbot&auth=changeme';
$connectTimeout = 5;
$timeout = 10;
$hideExtIP = true;

відповідно URL вашого хука буде мати вигляд

https://yourpublichost.com/tgtinygate_changeme/

Сподіваємось, що наступний набір опцій є доволі самоочевидним і не потребує порядкового розбору.

alter.ini

; Чи ввімкнено ClapTrapBot?
CLAPTRAPBOT_ENABLED=1

; Токен бота
CLAPTRAPBOT_TOKEN="1234567890:EXAMPLEfakeToken1234567890ABCDXXXXX"

; Режим відлагодження. Воно вам треба? Воно вам не треба.
CLAPTRAPBOT_DEBUG=0

; Рядок автентифікації - використовується для перевірки на автентичність, запитів до вебхука. Змініть на нормальний.
CLAPTRAPBOT_AUTH_STRING="changeme"

; URL вебхука - адреса, яка встановлюється для прийому та обробки запитів від бота.
CLAPTRAPBOT_HOOK_URL="https://yourpublichost.com/tgtinygate_changeme/"

; URL кабінету користувача - використовується для отримання даних користувача, авторизації та всякого такого.
CLAPTRAPBOT_USERSTATS_URL="https://my.ourisp.com/"

; Кількість кнопок основної клавіатури у рядку
CLAPTRAPBOT_PKBD_ROW=2

; Перелік ID увімкнених функцій ClapTrapBot. Функції буде розташовано на основній клавіатурі в тому ж порядку.
CLAPTRAPBOT_FEATURES="profile,announcements,credit,opayz,mypayments,support"

; Обмеження кількості дій за хвилину (APM) для ClapTrapBot. Вкажіть 0, щоб вимкнути.
CLAPTRAPBOT_THROTTLE_LIMIT=20

; Час блокування при перевищенні ліміту (у секундах). Вкажіть 0, щоб вимкнути.
CLAPTRAPBOT_THROTTLE_BAN_TIME=120

; Кількість платежів, що відображаються в списку "Мої платежі" за замовчуванням.
CLAPTRAPBOT_MY_PAYMENTS_LIMIT=3

; ID існуючого тега, для авторизованих користувачів ClapTrapBot. При авторизації тег буде встановлено. При відлогінюванні - знято. Вкажіть 0, щоб вимкнути.
CLAPTRAPBOT_USERS_TAGID=0

З боку ж кабінету, в свою чергу потрібен XMLAgent REST API щонайменше версії 2 (тобто кабінет актуальної версії Ubilling >= 1.5.8)

userstats.ini

 UBA_ENABLED=1

а також ви можете використати наступні опції

userstats.ini

TG_BOTNAME="ubillingdemobot"
TG_BOT_QR=1

щоб зробити, ось таку гарненьку автоматизовану авторизацію з кабінету користувача

Наразі наявними є наступні функції

Кожну з них, ви можете вмикати/вимикати/розташовувати як вам подобається, за допомогою опції CLAPTRAPBOT_FEATURES. На основній клавіатурі їх зображено власне в порядку, розташування ID функцій в значенні опції.

Після завершення базових налаштувань по конфігах, вам необхідно одноразово встановити хук вашого бота. Робиться це зручно та просто, за допомогою ось цього модуля

та виглядає приблизно наступним чином

Та нічо.