Dokumentacja Webchatix

Czat na żywo w duchu Telegram-first: odwiedzający pisze w widżecie na stronie, zespół odpowiada z Telegrama i panelu webowego. Po lewej sekcje, po prawej szczegóły.

W 5 minut

Otwórz bota → /start — powstaje konto na planie Free i pierwsza strona.
Skopiuj snippet HTML i wklej go na stronie przed </body>.
/panel — jednorazowy link do panelu webowego (albo pozycja „Panel webowy” w menu).
Zaproś operatora: /invite lub menu → „Zespół” → ➕.
Podłącz grupę Telegram: dodaj bota do grupy (albo wpisz w niej /addgroup) i przypisz ją do strony w «Trasach».
Wariant zapasowy — cała strona do jednej grupy: /bindsite site_key w grupie.

Plany i płatności

Rejestracja jest otwarta: /start w bocie tworzy konto w planie Free. Plany płatne kupuje się kartą w panelu, sekcja Faktury — płatność obsługuje Stripe.

Plan	Strony	Klienci / mies.	Operatorzy	Za miesiąc
`free`	1	30	1	$0
`basic`	20	1000	5	$10 ($8 przy płatności rocznej)
`unlimited`	∞	∞	∞	$20 ($16 przy płatności rocznej)

Ceny podajemy za miesiąc. Płatność za rok jest tańsza o 20% i pobierana jednorazowo ($96 i $192 rocznie); w panelu rok jest wybrany domyślnie.

Premium (od Basic): szablony, active invite, visibility rules, notatki, oceny.

Klient to unikalny odwiedzający, który rozpoczął rozmowę w bieżącym miesiącu kalendarzowym; licznik zeruje się 1. dnia.

Jak działa płatność

Panel → Faktury: bieżący plan, zużycie limitów, zmiana planu, lista płatności z linkami do PDF.
Dane karty nie trafiają na nasze serwery — strona płatności i portal należą do Stripe.
Zmianę planu w trakcie okresu Stripe rozlicza proporcjonalnie; anulowanie zostawia plan płatny do końca opłaconego okresu, potem konto wraca na Free.
Na adres e-mail z tej samej sekcji przychodzą potwierdzenie płatności, informacja o nieudanym obciążeniu i przypomnienie o odnowieniu.
Platform nadal może ustawić dowolny plan ręcznie: /setplan <id|tg> <plan>.

Menu bota

Główne menu po /start / /menu. Przyciski zwykle po dwa w rzędzie.

Pozycja	Co robi
🌐 Strony	Lista stron konta: ustawienia, Online/Offline, snippet, usuwanie.
👥 Zespół	Operatorzy / uczestnicy konta.
➕ Zaproś	Kod i deep-link dla nowego operatora.
💬 Grupy	Grupy Telegram przyjmujące zgłoszenia: podłącz, przypisz do strony, odłącz.
🔗 Panel webowy	Magic-link logowania (jednorazowy, ~10 min).
🗺 Trasy	Kto przyjmuje rozmowy z której strony/podstrony.
⚙️ Panel	Szybki dostęp: ops / sites / routes.
📝 Szablony	Szybkie odpowiedzi (od Basic).
💳 Plany i płatności	Ceny, płatność kartą, faktury (owner).
👑 Właściciel	Przekaż własność innemu uczestnikowi.
🗑 Usuń konto	Kaskadowe usunięcie po potwierdzeniu nazwą.
🛠 Platform	Tylko ADMIN_IDS: lista kont / setplan.

Karta strony

Online / Offline — pauza widżetu (czat offline).
Ustawienia — pola brandingu, invite, GDPR itd. (po 2 przyciski w rzędzie).
Operator — ustaw trasowanie na osobę lub grupę.
Usuń — z potwierdzeniem nazwą strony.

Komendy bota

Komenda	Kto	Znaczenie
`/start` [CODE]	wszyscy	Onboarding / realizacja zaproszenia.
`/menu`	member	Główne menu konta.
`/help`	wszyscy	Spis komend dla Twojej roli.
`/panel`	member	Magic-link do panelu webowego.
`/newsite` [nazwa \| origin]	admin+	Utwórz stronę (+ CORS origins).
`/sites`	admin+	Lista stron.
`/addgroup`	admin+ w grupie	Podłącz grupę jako operatora-grupę (bez chat_id).
`/bindsite` KEY	admin+ w grupie	Podłącz grupę jako czat zapasowy.
`/invite`	admin+	Zaproszenie operatora.
`/op_me` CODE	każdy	Przyjmij zaproszenie.
`/tpl`	member	Lista / add / del / wysyłka reply + /tpl id.
`/note`	member	Notatka do rozmowy (od Basic).
`/release`	member	Zwolnij rozmowę (+ prośba o ocenę).
`/lang`	wszyscy	Język interfejsu bota: en / pl / de / ru.
`/setrole` id role	owner	owner\|admin\|operator.
`/crm` on\|off	owner	Włącz/wyłącz most CRM konta.
`/deleteaccount`	owner	Usuń konto.
`/setplan`	platform	Zmień plan konta.
`/platform`	platform	Przegląd kont + link do /admin/platform/.
`/id`	na czacie	Pokaż chat_id.

Panel webowy

Logowanie tenanta: link z /panel albo token na /admin/login/. Właściciel platformy osobno: /admin/platform/ (hasło admin_password).

Sekcja	Po co
Przegląd	Liczniki i ostatnie rozmowy; nazwa firmy; most CRM dla ownera — przełącznik i link webhooka (puste — wspólny z config).
Strony	Tworzenie, snippet, pełne ustawienia widżetu.
Operatorzy	Uczestnicy, zaproszenia, role, grupy.
Trasy	Assignments: strona → operator/grupa.
Rozmowy	Historia, release, notatki, ocena.
Szablony	CRUD szablonów + podsumowanie ocen (od Basic).
Konta	Tylko platform: plan, suspend, impersonate, delete.

Ustawienia strony

Dostępne w bocie („Ustawienia”) oraz w panelu: Strony → koło zębate.

Pole	Znaczenie
Nazwa / tytuł / podtytuł	Nagłówek czatu.
Powitanie / logo	Pierwsza wiadomość i marka.
Online od–do, TZ, pauza	Status Online/Offline.
Eskalacja (min)	Alert przy braku odpowiedzi.
Kolor / pozycja / marginesy	Przycisk widżetu.
Język / dźwięk	en\|pl\|de\|ru oraz URL mp3.
Allowed origins	CORS: domeny po przecinku albo `*`.
Invite *	Zaproszenie w dymku (od Basic).
Visibility JSON	Gdzie pokazywać przycisk/invite (od Basic).
GDPR	Checkbox zgody przed pierwszą wysyłką.

Przykład visibility

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

Widżet na stronie

<script async src="https://TWOJA_DOMENA/widget/webchatix.js"
  data-site-key="TWÓJ_KEY"></script>

Sterowanie ze strony:

webchatix("show");   // pokaż przycisk
webchatix("hide");   // ukryj
webchatix("open");   // otwórz czat
webchatix("close");  // zamknij panel

Język widżetu bierze się z data-lang, potem z <html lang> strony, a na końcu z przeglądarki; obsługiwane są en / pl / de / ru, zapasowy to angielski. Po zmianie ustawień odśwież stronę klienta (wersja widżetu w query ?v=).

Jeśli strona ma ustawioną Content-Security-Policy, dopuść domenę widżetu w trzech dyrektywach: script-src, style-src i connect-src. Wygląd widżet ładuje z osobnego pliku webchatix.css, więc nie trzeba dla niego trzymać 'unsafe-inline' w style-src.

Operatorzy i role

owner — pełna kontrola, prośby o plan, usunięcie konta, CRM, przekazanie własności.
admin — strony, zaproszenia, trasy, ustawienia.
operator — odpowiedzi w rozmowach, notatki/szablony zależnie od planu.

Jeden użytkownik Telegrama = jedno własne konto. W cudzych kontach można być operatorem na zaproszenie.

Grupy

Operatorem może być nie tylko osoba, ale i grupa Telegram: zgłoszenie trafia kartą na czat, odpowiada dowolny uczestnik przez Reply. Podłączenie: dodaj bota do grupy (menu → 💬 Grupy → „Podłącz grupę”) albo wpisz w niej /addgroup — chat_id nie trzeba wpisywać, bot pobiera go sam. Grupy nie zajmują limitu operatorów w planie.

Rozmowy

Wiadomość klienta idzie do Telegrama (grupa/operator według trasy).
Przyjmij — claim; wiadomość systemowa w historii.
Przekaż — tylko do aktywnego uczestnika tego samego konta.
Zwolnij / release — można poprosić odwiedzającego o ocenę.
Notatki — widoczne dla zespołu, nie dla klienta (od Basic).
Szablony — reply na rozmowę + /tpl id albo przycisk szablonu → Reply.

Platforma (właściciel aplikacji)

ID Telegrama z ADMIN_IDS / platform_tg_ids + hasło admin_password.

Web: /admin/platform/ → konta, setplan, suspend, impersonate, delete.
Bot: /platform, /setplan id|tg plan.

Impersonate jest logowany w platform_audit (kto/IP/konto).

Bezpieczeństwo i GDPR

Konta są izolowane po account_id.
Magic-link jest jednorazowy; liczba wydawanych linków jest limitowana.
Suspend wyłącza widżet, bota i panel tenanta.
CORS: ustaw allowed_origins (nie zostawiaj * na produkcji bez potrzeby).
Checkbox GDPR — przed pierwszą wiadomością klienta.
Limit uploadu zależny od planu (max_upload_mb).
Nie więcej niż 10 nowych stron na godzinę na konto.

Backup i wdrożenie

Skrypt backupu SQLite z rotacją:

chmod +x scripts/backup-sqlite.sh
# cron codziennie:
15 3 * * * /path/to/chat-widget/scripts/backup-sqlite.sh

Kopie: data/backups/chat_*.sqlite.gz (domyślnie 14 sztuk).

Po aktualizacji rewrite w aaPanel dodaj docs obok faq|contact|blog oraz prefiksy językowe pl|de|ru, a następnie zrestartuj bota.