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

1. Bot öffnen → /start — es entstehen ein Konto im Tarif Free und die erste Website.
2. HTML-Snippet kopieren und auf der Website vor </body> einfügen.
3. /panel — Einmal-Link ins Web-Dashboard (oder der Menüpunkt „Web-Dashboard“).
4. Eine Person einladen: /invite oder Menü → „Team“ → ➕.
5. Telegram-Gruppe verbinden: Bot zur Gruppe hinzufügen (oder dort /addgroup schreiben) und sie unter «Routen» einer Website zuweisen.
6. 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.

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.

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

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).

Website-Einstellungen

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

KI-Antwort (Gemini)

Der Besucher schreibt, die Operatoren schweigen — nach der eingestellten Zahl von Minuten antwortet Google Gemini im Chat. Der Besucher sieht die Antwort im Widget, die Operatoren bekommen in Telegram eine Karte „KI hat geantwortet“ mit demselben Text, damit niemand dasselbe wiederholt.

• Pro Website aktivierbar: Websites → Zahnrad → KI-Antwort. Dort stehen auch die Verzögerung und das Feld „Was die KI über die Firma wissen soll“ — Öffnungszeiten, Versand, was nicht versprochen werden darf.
• Eine Antwort des Menschen setzt den Zähler zurück; einen vom Operator übernommenen (claim) Dialog rührt die KI nicht an.
• Die KI-Antwort hebt die Eskalation nicht auf: Der Admin wird weiterhin benachrichtigt, dass kein Mensch geantwortet hat.
• Das Modell antwortet kurz, erfindet keine Preise oder Termine und gibt auf direkte Nachfrage zu, ein automatischer Assistent zu sein.
• Der API-Schlüssel wird einmal pro Installation gesetzt: gemini_api_key in config/config.php (Schlüssel aus Google AI Studio, mit kostenlosem Kontingent). Ohne Schlüssel bewirkt die Checkbox nichts.

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 / uk / be / ar, 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|uk|be|ar ergänzen, danach den Bot neu starten.