====== ClaptrapBot - Користувацький Telegram бот ======

{{:claptrap.png |}}

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

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


====== Реєстрація вашого бота ======

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

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

====== Веб хук ======

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

<code>
https://yourhost.com/billing/?module=claptrapbot
</code>

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

<file ini alter.ini>
CLAPTRAPBOT_AUTH_STRING="changeme"
</file>

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

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


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

====== Доступ до веб хуку ======

Варто також помітити, що Telegram [[https://core.telegram.org/bots/api#setwebhook|дозволяє]] використовувати як веб-хуки, **тільки https** посилання. І так, тільки на портах 443, 80, 88, 8443. Також очевидно, що якщо ви не знехтували нашими [[security|рекомендаціями що до безпеки]] доступ до адміністративного інтерфейсу білінгу, у вас повинен би бути обмеженим ззовні. Щоб не гратись і не дозволяти доступ поштучно, для Telegram до цілої адмінки, ви можете, прокинути посилання на ваш вебхук в якусь іншу URL засобами вашого веб сервера, ну скажімо [[https://lapaste.in.ua/?v=0kot1hrg|якось так]], або ж скористатись мінімалістичним web-proxy, наприклад [[https://github.com/nightflyza/tgtinygate|tgtinygate aka TGTG]], спеціально зробленим під ці задачі. Також ніхто вас не зобов'язує тримати його прямо на білінговому сервері. Наприклад, ваш Ubilling знаходиться на хості з сірою IP адресою, десь за NAT-ом, або до нього дропаються всі звернення окрім як від вашої внутрішньої інфраструктури. В цьому випадку, ви можете, розмітити TGTG на будь-якому хості, з працюючим https, доступному ззовні:

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

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

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

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

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

<code>
https://yourpublichost.com/tgtinygate_changeme/
</code>

====== Файли конфігурації ======

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

<file ini 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
</file>

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

<file ini userstats.ini>
 UBA_ENABLED=1
</file>


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

<file ini userstats.ini>
TG_BOTNAME="ubillingdemobot"
TG_BOT_QR=1
</file>

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

{{:userstatstgbotauth.png|}}


====== Наявні функції боту  ======

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

^   ^ ID функції ^ Опис ^
| 👨‍💼 | profile | Відображає інформацію профілю користувача (ПІБ, адреса, мобільний, тариф, баланс, IP, кредит, стан облікового запису, платіжний ID) |
| 📺 | catv | Відображає профіль користувача КТБ (адреса, договір, телефон, тариф, баланс) |
| ⏱️ | credit | Дозволяє користувачам запитати або перевірити можливість кредиту з підтвердженням умов надання послуги |
| 📢 | announcements | Відображає активні оголошення зі статусом прочитано/непрочитано та можливістю позначити всі як прочитані |
| 💳 | opayz | Список доступних методів онлайн-оплати з прямими посиланнями |
| 💸 | mypayments | Показує історію платежів користувача з пагінацією (останні, більше, всі) |
| 📞 | support | Дозволяє користувачам переглядати та створювати тікети в хелпдеску. |

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

====== Встановлення хуку  ======

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

{{:cltpmgr0.png|}}

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

{{:claptraphookinstall.png|}}


====== А далі що? ======

Та нічо.


{{:claptrapbot_scr1.png|}}

{{:claptrapbot_scr2.png|}}

{{:claptrapbot_scr3.png|}}

{{:claptrapbot_scr4.png|}}