Webchatix-Dokumentation

Telegram-first Live-Chat: Besucher schreiben ins Website-Widget, Ihr Team antwortet aus Telegram und dem Web-Dashboard. Links die Abschnitte, rechts die Details.

In 5 Minuten

Bot öffnen → /start — es entstehen ein Konto im Tarif Free und die erste Website.
HTML-Snippet kopieren und auf der Website vor </body> einfügen.
/panel — Einmal-Link ins Web-Dashboard (oder der Menüpunkt „Web-Dashboard“).
Eine Person einladen: /invite oder Menü → „Team“ → ➕.
Telegram-Gruppe verbinden: Bot zur Gruppe hinzufügen (oder dort /addgroup schreiben) und sie unter «Routen» einer Website zuweisen.
Fallback für eine ganze Website in einer Gruppe: /bindsite site_key in der Gruppe.

Tarife und Zahlung

Die Registrierung ist offen: /start im Bot legt ein Konto im Tarif Free an. Bezahlte Tarife kauft man per Karte im Dashboard, Bereich Rechnungen — die Zahlung läuft über Stripe.

Tarif	Websites	Kunden / Monat	Personen	Pro Monat
`free`	1	30	1	$0
`basic`	20	1000	5	$10 ($8 bei Jahreszahlung)
`unlimited`	∞	∞	∞	$20 ($16 bei Jahreszahlung)

Die Preise gelten pro Monat. Die Jahreszahlung ist 20% günstiger und wird einmalig abgebucht ($96 und $192 im Jahr); im Dashboard ist das Jahr vorausgewählt.

Premium (ab Basic): Vorlagen, Active Invite, Visibility Rules, Notizen, Bewertungen.

Ein Kunde ist ein eindeutiger Besucher, der im laufenden Kalendermonat einen Chat begonnen hat; der Zähler startet am 1. neu.

So funktioniert die Zahlung

Dashboard → Rechnungen: aktueller Tarif, Verbrauch, Tarifwechsel, Liste der Zahlungen mit PDF-Links.
Kartendaten erreichen unsere Server nie — Zahlungsseite und Kundenportal gehören Stripe.
Einen Tarifwechsel mitten in der Periode rechnet Stripe anteilig ab; nach einer Kündigung bleibt der bezahlte Tarif bis zum Periodenende, danach fällt das Konto auf Free zurück.
An die E-Mail-Adresse aus demselben Bereich gehen Zahlungsbeleg, Hinweis auf eine fehlgeschlagene Abbuchung und die Erinnerung an die Verlängerung.
Platform kann weiterhin jeden Tarif manuell setzen: /setplan <id|tg> <plan>.

Bot-Menü

Das Hauptmenü nach /start / /menu. Die Schaltflächen stehen meist zu zweit in einer Reihe.

Eintrag	Funktion
🌐 Websites	Websites des Kontos: Einstellungen, Online/Offline, Snippet, Löschen.
👥 Team	Mitglieder des Kontos.
➕ Einladen	Code und Deep-Link für eine neue Person.
💬 Gruppen	Telegram-Gruppen, die Anfragen erhalten: verbinden, Website zuweisen, trennen.
🔗 Web-Dashboard	Magic-Login-Link (einmalig, ~10 Min.).
🗺 Routen	Wer Dialoge von welcher Website/Seite bekommt.
⚙️ Panel	Schnellzugriff: ops / sites / routes.
📝 Vorlagen	Schnellantworten (ab Basic).
💳 Tarife und Zahlung	Preise, Kartenzahlung, Rechnungen (owner).
👑 Eigentum	Eigentum an ein anderes Mitglied übergeben.
🗑 Konto löschen	Kaskadierendes Löschen nach Bestätigung per Name.
🛠 Platform	Nur ADMIN_IDS: Kontenliste / setplan.

Website-Karte

Online / Offline — Widget pausieren (Chat offline).
Einstellungen — Branding-Felder, Invite, DSGVO usw. (2 Schaltflächen je Reihe).
Zuständigkeit — Routing auf eine Person oder Gruppe setzen.
Löschen — mit Bestätigung durch den Website-Namen.

Bot-Befehle

Befehl	Wer	Bedeutung
`/start` [CODE]	alle	Onboarding / Einladung einlösen.
`/menu`	member	Hauptmenü des Kontos.
`/help`	alle	Befehlsübersicht für deine Rolle.
`/panel`	member	Magic-Link ins Web-Dashboard.
`/newsite` [Name \| Origin]	admin+	Website anlegen (+ CORS-Origins).
`/sites`	admin+	Liste der Websites.
`/addgroup`	admin+ in Gruppe	Gruppe als Gruppen-Operator verbinden (ohne chat_id).
`/bindsite` KEY	admin+ in Gruppe	Gruppe als Fallback-Chat verbinden.
`/invite`	admin+	Einladung ausstellen.
`/op_me` CODE	alle	Einladung annehmen.
`/tpl`	member	Liste / add / del / Senden per Reply + /tpl id.
`/note`	member	Notiz zum Dialog (ab Basic).
`/release`	member	Dialog freigeben (+ Bewertung anfragen).
`/lang`	alle	Sprache der Bot-Oberfläche: en / pl / de / ru.
`/setrole` id role	owner	owner\|admin\|operator.
`/crm` on\|off	owner	CRM-Brücke des Kontos ein-/ausschalten.
`/deleteaccount`	owner	Konto löschen.
`/setplan`	platform	Tarif des Kontos ändern.
`/platform`	platform	Kontenübersicht + Link zu /admin/platform/.
`/id`	im Chat	chat_id anzeigen.

Web-Dashboard

Tenant-Login: der Link aus /panel oder ein Token auf /admin/login/. Für die Plattform-Eigentümerschaft separat: /admin/platform/ (Passwort admin_password).

Bereich	Wozu
Übersicht	Zähler und letzte Dialoge; Firmenname; CRM-Brücke für owner — Schalter und Webhook-Link (leer — der gemeinsame aus config).
Websites	Anlegen, Snippet, vollständige Widget-Einstellungen.
Team	Mitglieder, Einladungen, Rollen, Gruppen.
Routen	Assignments: Website → Person/Gruppe.
Dialoge	Verlauf, Release, Notizen, Bewertung.
Vorlagen	CRUD für Vorlagen + Bewertungsübersicht (ab Basic).
Konten	Nur platform: Tarif, suspend, impersonate, delete.

Website-Einstellungen

Verfügbar im Bot („Einstellungen“) und im Web unter Websites → Zahnrad.

Feld	Bedeutung
Name / Titel / Untertitel	Kopfzeile des Chats.
Begrüßung / Logo	Erste Nachricht und Marke.
Online von–bis, TZ, Pause	Status Online/Offline.
Eskalation (Min.)	Alarm, wenn keine Antwort kommt.
Farbe / Position / Abstände	Der Widget-Button.
Sprache / Ton	en\|pl\|de\|ru und eine mp3-URL.
Allowed origins	CORS: Domains per Komma oder `*`.
Invite *	Einladung als Sprechblase (ab Basic).
Visibility JSON	Wo Button/Invite erscheinen (ab Basic).
DSGVO	Einwilligungs-Checkbox vor dem ersten Senden.

Visibility-Beispiel

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

Widget auf der Website

<script async src="https://IHRE_DOMAIN/widget/webchatix.js"
  data-site-key="IHR_KEY"></script>

Steuerung von der Seite aus:

webchatix("show");   // Button anzeigen
webchatix("hide");   // ausblenden
webchatix("open");   // Chat öffnen
webchatix("close");  // Panel schließen

Die Widget-Sprache kommt aus data-lang, dann aus dem <html lang> der Seite, dann aus dem Browser; unterstützt sind en / pl / de / ru, Rückfallsprache ist Englisch. Nach Änderungen an den Einstellungen die Kundenseite neu laden (die Widget-Version steht im Query ?v=).

Wenn die Website eine Content-Security-Policy setzt, erlauben Sie die Widget-Domain in drei Direktiven: script-src, style-src und connect-src. Das Widget lädt sein Aussehen aus der separaten Datei webchatix.css, ein 'unsafe-inline' in style-src ist dafür also nicht mehr nötig.

Rollen im Team

owner — volle Kontrolle, Tarifanfragen, Kontolöschung, CRM, Eigentumsübergabe.
admin — Websites, Einladungen, Routen, Einstellungen.
operator — Antworten in Dialogen, Notizen/Vorlagen je nach Tarif.

Ein Telegram-Konto = ein eigenes Konto. In fremden Konten kann man per Einladung als operator mitarbeiten.

Gruppen

Nicht nur Personen, auch eine Telegram-Gruppe kann Operator sein: Die Anfrage kommt als Karte in den Chat, beantworten kann sie jedes Mitglied per Reply. Verbinden: Bot zur Gruppe hinzufügen (Menü → 💬 Gruppen → „Gruppe verbinden“) oder dort /addgroup schreiben — keine chat_id nötig, der Bot ermittelt sie selbst. Gruppen zählen nicht zum Operator-Limit des Tarifs.

Dialoge

Die Kundennachricht geht an Telegram (Gruppe/Person gemäß Route).
Übernehmen — Claim; eine Systemnachricht landet im Verlauf.
Übergeben — nur an ein aktives Mitglied desselben Kontos.
Freigeben / Release — Sie können den Besucher um eine Bewertung bitten.
Notizen — für das Team sichtbar, nicht für Kundinnen und Kunden (ab Basic).
Vorlagen — Reply auf den Dialog + /tpl id oder Vorlagen-Button → Reply.

Plattform (Eigentümerschaft der Anwendung)

Telegram-IDs aus ADMIN_IDS / platform_tg_ids + Passwort admin_password.

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

Impersonate wird in platform_audit protokolliert (wer/IP/Konto).

Sicherheit und DSGVO

Konten sind über account_id isoliert.
Der Magic-Link gilt einmalig; die Ausgabe ist limitiert.
Suspend schaltet Widget, Bot und Tenant-Dashboard ab.
CORS: setzen Sie allowed_origins (kein * in Produktion ohne Grund).
Die DSGVO-Checkbox erscheint vor der ersten Kundennachricht.
Upload-Kontingent je nach Tarif (max_upload_mb).
Höchstens 10 neue Websites pro Stunde und Konto.

Backup und Deployment

SQLite-Backup-Skript mit Rotation:

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

Kopien: data/backups/chat_*.sqlite.gz (standardmäßig 14 Stück).

Nach dem Aktualisieren der Rewrite-Regeln in aaPanel docs neben faq|contact|blog und die Sprachpräfixe pl|de|ru ergänzen, danach den Bot neu starten.