Зміст
ClaptrapBot - Користувацький Telegram бот
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 ; Вмикає інтеграцію з хелпдеском. Базово - миттєва відправка відповідей на тікети в чат з користувачем. ; Можливі значення: 0 - вимкнено, 1 - ввімкнено, 2 - чекбокс відсилки відповідей в Телеграм увімкнено за замовчуванням. CLAPTRAPBOT_HELPDESK_INTEGRATION=0
З боку ж кабінету, в свою чергу потрібен XMLAgent REST API щонайменше версії 2 (тобто кабінет актуальної версії Ubilling >= 1.5.8)
- userstats.ini
UBA_ENABLED=1
а також ви можете використати наступні опції
- userstats.ini
TG_BOTNAME="ubillingdemobot" TG_BOT_QR=1
щоб зробити, ось таку гарненьку автоматизовану авторизацію з кабінету користувача
Наявні функції боту
Наразі наявними є наступні функції
| ID функції | Опис | |
|---|---|---|
| 👨💼 | profile | Відображає інформацію профілю користувача (ПІБ, адреса, мобільний, тариф, баланс, IP, кредит, стан облікового запису, платіжний ID) |
| 📺 | catv | Відображає профіль користувача КТБ (адреса, договір, телефон, тариф, баланс) |
| ⏱️ | credit | Дозволяє користувачам запитати або перевірити можливість кредиту з підтвердженням умов надання послуги |
| 📢 | announcements | Відображає активні оголошення зі статусом прочитано/непрочитано та можливістю позначити всі як прочитані |
| 💳 | opayz | Список доступних методів онлайн-оплати з прямими посиланнями |
| 💸 | mypayments | Показує історію платежів користувача з пагінацією (останні, більше, всі) |
| 📞 | support | Дозволяє користувачам переглядати та створювати тікети в хелпдеску. |
Кожну з них, ви можете вмикати/вимикати/розташовувати як вам подобається, за допомогою опції CLAPTRAPBOT_FEATURES. На основній клавіатурі їх зображено власне в порядку, розташування ID функцій в значенні опції.
Встановлення хуку
Після завершення базових налаштувань по конфігах, вам необхідно одноразово встановити хук вашого бота. Робиться це зручно та просто, за допомогою ось цього модуля
та виглядає приблизно наступним чином
А далі що?
Та нічо.
У випадку, якщо у вас ввімкнено інтеграцію з хелпдеском при відповіді на тікет користувача, можна миттєво надсилати йому відповіді в Telegram прямо в чат з ботом. Біля кожної відповіді, у випадку якщо її було надіслано відображатиметься стан надсилання. Також можливе редагування чи видалення відповіді в режимі реального часу.
Зрозуміло що, у випадку якщо він щонайменше залогінений в чаті з ботом, що відображається наступним чином:
