Документація Webchatix

Live chat, що працює насамперед через Telegram: відвідувач пише у віджет на сайті, а команда відповідає з Telegram і вебпанелі. Ліворуч — розділи, праворуч — подробиці.

За 5 хвилин

Відкрийте бота → /start — буде створено акаунт на тарифі Free і перший сайт.
Скопіюйте HTML-сніпет і вставте його на сайт перед </body>.
/panel — одноразове посилання до веб-кабінету (або пункт меню «Вебпанель»).
Запросіть оператора: /invite або меню → «Команда» → ➕.
Під’єднайте Telegram-групу: додайте бота до групи (або надішліть у ній /addgroup) і призначте її сайту в розділі «Маршрути».
Запасний варіант — увесь сайт в одну групу: /bindsite site_key у самій групі.

Тарифи й оплата

Реєстрація відкрита: /start у боті створює акаунт на тарифі Free. Платні тарифи оплачуються карткою в кабінеті, розділ Рахунки — платіж проходить через Stripe.

Тариф	Сайти	Клієнти / міс.	Оператори	На місяць
`free`	1	30	1	$0
`basic`	20	1000	5	$10 ($8 у разі оплати за рік)
`unlimited`	∞	∞	∞	$20 ($16 у разі оплати за рік)

Ціни вказано за місяць. Оплата за рік на 20% дешевша і списується одним платежем ($96 і $192 на рік); у кабінеті річну оплату вибрано за замовчуванням.

Premium (від Basic): шаблони, активне запрошення, правила видимості, нотатки, оцінки.

Клієнт — унікальний відвідувач, який почав діалог у поточному календарному місяці; лічильник обнуляється 1-го числа.

Як працює оплата

Кабінет → Рахунки: поточний тариф, використання лімітів, зміна тарифу, перелік рахунків із посиланнями на PDF.
Дані картки не потрапляють на наші сервери — сторінка оплати й портал керування належать Stripe.
Якщо змінити тариф посеред періоду, Stripe перерахує суму пропорційно; після скасування платний тариф діє до кінця оплаченого періоду, а потім акаунт повертається на Free.
На пошту, вказану в цьому ж розділі, надходять чек, повідомлення про невдале списання та нагадування про продовження за кілька днів.
Platform, як і раніше, може встановити будь-який тариф вручну: /setplan <id|tg> <plan>.

Меню бота

Головне меню після /start / /menu. Кнопки зазвичай розташовані по дві в ряд.

Пункт	Що робить
🌐 Сайти	Перелік сайтів акаунта: налаштування, Online/Offline, сніпет, видалення.
👥 Команда	Оператори / учасники акаунта.
➕ Запросити	Код і deep link для нового оператора.
💬 Групи	Telegram-групи, що приймають звернення: під’єднати, призначити сайту, від’єднати.
🔗 Вебпанель	Magic link для входу (одноразове, ~10 хв).
🗺 Маршрути	Хто отримує діалоги з якого сайту/сторінки.
⚙️ Панель	Швидкий доступ: ops / sites / routes.
📝 Шаблони	Готові відповіді (від Basic).
💳 Тарифи й оплата	Ціни, оплата карткою, рахунки (owner).
👑 Власник	Передати права власника іншому учаснику.
🗑 Видалити акаунт	Каскадне видалення після підтвердження назвою.
🛠 Platform	Лише ADMIN_IDS: перелік акаунтів / setplan.

Картка сайту

Online / Offline — призупинити віджет (чат офлайн).
Налаштування — поля брендування, запрошення, GDPR тощо (по дві кнопки в ряд).
Оператор — спрямувати цей сайт на людину або групу.
Видалити — з підтвердженням назвою сайту.

Команди бота

Команда	Хто	Призначення
`/start` [CODE]	усі	Початок роботи / активація запрошення.
`/menu`	member	Головне меню акаунта.
`/help`	усі	Довідка з команд для вашої ролі.
`/panel`	member	Magic link до вебпанелі.
`/newsite` [назва \| origin]	admin+	Створити сайт (+ CORS origins).
`/addgroup`	admin+ у групі	Під’єднати групу як оператора-групу (chat_id не потрібен).
`/bindsite` KEY	admin+ у групі	Прив’язати групу як резервний чат.
`/invite`	admin+	Запрошення для оператора.
`/op_me` CODE	будь-хто	Прийняти запрошення.
`/tpl`	member	Перелік / add / del / надсилання відповіддю + /tpl id.
`/note`	member	Нотатка до діалогу (від Basic).
`/release`	member	Звільнити діалог (+ запит оцінки).
`/lang`	усі	Мова інтерфейсу бота: en / pl / de / ru / uk / be / ar.
`/setrole` id role	owner	owner\|admin\|operator.
`/crm` on\|off	owner	Увімкнути/вимкнути CRM-міст акаунта.
`/deleteaccount`	owner	Видалити акаунт.
`/setplan`	platform	Змінити тариф акаунта.
`/platform`	platform	Огляд акаунтів + посилання на /admin/platform/.
`/id`	у чаті	Показати chat_id.

Вебпанель

Вхід для тенанта: посилання з /panel або токен на /admin/login/. Власник платформи має окремий вхід: /admin/platform/ (пароль admin_password).

Розділ	Для чого
Огляд	Лічильники й останні діалоги; назва компанії; CRM-міст для owner — перемикач і посилання вебхука (якщо порожньо — береться спільне з config).
Сайти	Створення, сніпет, повні налаштування віджета.
Оператори	Учасники, запрошення, ролі, групи.
Маршрути	Призначення: сайт → оператор/група.
Діалоги	Історія, звільнення, нотатки, оцінка.
Шаблони	Створення й редагування шаблонів + зведення оцінок (від Basic).
Акаунти	Лише platform: тариф, suspend, impersonate, delete.

Налаштування сайту

Доступні в боті («Налаштування») і у вебпанелі: Сайти → шестірня.

Поле	Значення
Назва / заголовок / підзаголовок	Шапка чату.
Привітання / логотип	Перше повідомлення і бренд.
Онлайн з–до, TZ, пауза	Статус Online/Offline.
Ескалація (хв)	Сповіщення, якщо немає відповіді.
Колір / позиція / відступи	Кнопка віджета.
Мова / звук	en\|pl\|de\|ru\|uk\|be\|ar і URL mp3.
Allowed origins	CORS: домени через кому або `*`.
Invite *	Запрошення-бульбашка (від Basic).
Visibility JSON	Де показувати кнопку/запрошення (від Basic).
GDPR	Прапорець згоди перед першим надсиланням.
ШІ-відповідач	Відповідає відвідувачу, якщо ніхто не відповів N хвилин (за замовчуванням 3).

ШІ-відповідач (Gemini)

Відвідувач написав, а оператор мовчить — через задану кількість хвилин у діалозі відповідає Google Gemini. Відвідувач бачить відповідь у віджеті, а оператори отримують у Telegram картку «Відповів ШІ» з тим самим текстом, щоб ніхто не повторював сказане.

Вмикається для кожного сайту окремо: Сайти → шестірня → ШІ-відповідач. Там само — затримка і поле «Що ШІ має знати про компанію»: години роботи, доставка, чого не можна обіцяти.
Відповідь людини скидає відлік; діалог, який оператор узяв на себе, ШІ не чіпає.
Відповідь ШІ не скасовує ескалацію: адміністратор усе одно отримає сповіщення, що жива людина не відповіла.
Модель відповідає коротко, не вигадує цін і термінів, а на пряме запитання визнає, що вона автоматичний асистент.
Ключ API задається один раз для всієї інсталяції: gemini_api_key у config/config.php (його можна отримати в Google AI Studio, там є безплатний ліміт). Без ключа прапорець нічого не робить.

Приклад visibility

{"include":["/pricing","/contacts"],"exclude":["/admin"],"desktop":true,"mobile":true}

Віджет на сайті

<script async src="https://ВАШ_ДОМЕН/widget/webchatix.js"
  data-site-key="ВАШ_KEY"></script>

Керування зі сторінки:

webchatix("show");   // показати кнопку
webchatix("hide");   // сховати
webchatix("open");   // відкрити чат
webchatix("close");  // закрити панель

Мова віджета визначається за data-lang, далі за <html lang> сторінки, далі за браузером; підтримуються en / pl / de / ru / uk / be / ar, запасна — англійська. Після зміни налаштувань оновіть сторінку клієнта (версія віджета передається в query ?v=).

Якщо на сайті налаштовано Content-Security-Policy, дозвольте домен віджета у трьох директивах: script-src, style-src і connect-src. Стилі віджет підвантажує окремим файлом webchatix.css, тож тримати заради нього 'unsafe-inline' у style-src не потрібно.

Оператори й ролі

owner — повний контроль, запити щодо тарифу, видалення акаунта, CRM, передача прав власника.
admin — сайти, запрошення, маршрути, налаштування.
operator — відповіді в діалогах, нотатки/шаблони залежно від тарифу.

Один користувач Telegram = один власний акаунт. В інших акаунтах можна бути оператором за запрошенням.

Групи

Крім людей, оператором може бути Telegram-група: звернення надходять у чат карткою, і відповісти може будь-хто з учасників — через Reply на картку. Щоб під’єднати групу, додайте до неї бота (меню → 💬 Групи → «Під’єднати групу») або надішліть у групі /addgroup — вводити chat_id не потрібно, бот визначить його сам. Групи не враховуються в ліміт операторів за тарифом.

Діалоги

Повідомлення клієнта надходить у Telegram (групі/оператору відповідно до маршруту).
Прийняти — бере діалог на себе; в історії з’являється системне повідомлення.
Передати — лише активному учаснику того самого акаунта.
Звільнити — можна попросити відвідувача оцінити розмову.
Нотатки — бачить команда, але не клієнт (від Basic).
Шаблони — Reply на діалог + /tpl id або кнопка шаблону → Reply.

Платформа (власник застосунку)

Telegram ID з ADMIN_IDS / platform_tg_ids плюс пароль admin_password.

Веб: /admin/platform/ → акаунти, setplan, suspend, impersonate, delete.
Бот: /platform, /setplan id|tg plan.

Вхід від імені акаунта (impersonate) записується в platform_audit (хто/IP/акаунт).

Безпека й GDPR

Акаунти ізольовані за account_id.
Magic link одноразове; видачу посилань обмежено за частотою.
Suspend вимикає віджет, бота й кабінет тенанта.
CORS: задайте allowed_origins (не залишайте * у продакшені без потреби).
Прапорець GDPR показується до першого повідомлення клієнта.
Квота на завантаження файлів залежить від тарифу (max_upload_mb).
Не більше 10 нових сайтів на годину для одного акаунта.

Резервні копії та деплой

Скрипт резервного копіювання SQLite з ротацією:

chmod +x scripts/backup-sqlite.sh
# cron щодня:
15 3 * * * /path/to/chat-widget/scripts/backup-sqlite.sh

Копії: data/backups/chat_*.sqlite.gz (за замовчуванням 14 штук).

Після оновлення правил rewrite в aaPanel додайте docs поруч із faq|contact|blog і мовні префікси pl|de|ru|uk|be|ar, а потім перезапустіть бота.