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.

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 /account/login/.

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://webchatix.online/widget/webchatix.js"
  data-site-key="SITE_KEY"></script>

Steuerung von der Seite aus:

webchatix("show");   // Button anzeigen
webchatix("hide");   // ausblenden
webchatix("open");   // Chat öffnen
webchatix("close");  // Panel schließen
webchatix("form", "report"); // Formularabsendung zählen (Statistik)

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.

Besuchsstatistik und API

Das Widget zählt die Besuche der Website, auf der es installiert ist. Die Statistik wird ohne Zeitlimit als Tageszähler gespeichert (Tage in UTC); ein Bericht kann jeden Zeitraum abdecken. Abrufbar sind die Daten über eine API mit dem geheimen Kontoschlüssel — ein Schlüssel öffnet alle Websites des Kontos.

Das normale Chat-Snippet erfasst die Statistik bereits — Sie müssen nichts hinzufügen.

Installation nur für die Statistik (ohne Oberfläche)

Das Attribut data-mode="stats" installiert das Widget ohne Button, Chatfenster und Styles: Das Skript sendet pro Seite nur einen leichten Hit. Das Pixel in <noscript> ist optional — es erfasst Bots, die kein JavaScript ausführen, aber Bilder laden.

<script async src="https://webchatix.online/widget/webchatix.js"
  data-site-key="SITE_KEY" data-mode="stats"></script>
<noscript><img src="https://webchatix.online/wx-api.php?action=track&site_key=SITE_KEY"
  width="1" height="1" alt="" style="position:absolute"></noscript>

SITE_KEY ist der öffentliche Website-Schlüssel — derselbe wie im Chat-Snippet (Bot: „📋 Installationscode“, Dashboard: „Websites“). Das ist nicht der API-Schlüssel wxs_…: Der ist geheim und gehört nie in den Seitencode.

Ist für die Website Allowed origins gesetzt, werden Hits von Seiten anderer Domains nicht gezählt.

Formulare ohne <form>-Tag

Ein normales <form> erfasst das Widget selbst — über das Ereignis submit, auch wenn die Website es per fetch sendet. Oft besteht ein Formular aber nur aus Feldern und einem <button type="button">, und das JavaScript der Website sendet die Daten; dann gibt es kein submit-Ereignis und die Absendung wird nicht gezählt. Für solche Formulare gibt es zwei Wege.

1. Das Attribut data-wx-form am Absende-Button: Ein Klick zählt als Absendung des Formulars mit diesem Namen. Ein deaktivierter Button (disabled) zählt nicht, ein Doppelklick ergibt eine Absendung.

<button type="button" class="get_report" data-wx-form="report">…</button>

2. Ein Aufruf aus dem Code der Website — wenn die Absendung z. B. erst nach erfolgreicher Prüfung der Felder zählen soll. Funktioniert mit dem normalen Widget und mit data-mode="stats". Kann Ihr Code vor dem Laden des Widgets laufen, setzen Sie den Platzhalter darüber — die Aufrufe landen in einer Warteschlange und gehen nicht verloren.

// nach erfolgreicher Prüfung der Felder
webchatix("form", "report");

// Platzhalter — über den Aufrufen, falls der Code vor dem Widget läuft
window.webchatix = window.webchatix || function () {
  (webchatix.q = webchatix.q || []).push(arguments);
};

Das Attribut data-wx-form an einem <form> oder an dessen Submit-Button setzt den Formularnamen im Bericht statt #id / name / action.

API-Schlüssel

Der Schlüssel wxs_… gilt für das ganze Konto. Wo Sie ihn finden und ersetzen: im Telegram-Bot — Schaltfläche 🔑 API-Schlüssel im Hauptmenü (dort auch eine Übersicht aller Websites), im Dashboard — Websites → Zahnrad. „Schlüssel ersetzen“ erzeugt einen neuen, der alte funktioniert sofort nicht mehr. Owner und Admins des Kontos sehen und ersetzen ihn.

Der Schlüssel ist geheim: Der öffentliche site_key taugt nicht zum Lesen, und der Schlüssel selbst gehört nicht in den Seitencode — fragen Sie die Statistik von Ihrem Server ab. Die Statistik einer Website gibt es auch im Bot: 🌐 Websites → Website → 📊 Statistik.

Der Schlüssel wird auf eine dieser Arten übergeben: Header X-Stats-Key: wxs_…, Header Authorization: Bearer wxs_… oder Parameter ?key=wxs_….

Zwei Schlüssel

Ein API-Schlüssel im Pixel oder Seitencode ist für jeden Besucher über „Quelltext anzeigen“ sichtbar — er könnte Ihre Statistik lesen und verfälschen. Ist der Schlüssel nach außen gelangt, ersetzen Sie ihn.

GET /stats-api.php?action=stats

Parameter: site_key — nur diese Website des Kontos (ohne — alle Websites); der Zeitraum — days (die letzten N Tage bis heute, 1–366, Standard 7) oder from und to (Daten JJJJ-MM-TT einschließlich, höchstens 366 Tage; ist nur ein Datum angegeben, wird das andere um days Tage gezählt); limit — wie viele Seiten in der Top-Liste jeder Website (1–1000, Standard 50).

curl -H "X-Stats-Key: wxs_…" "https://webchatix.online/stats-api.php?action=stats&days=7&limit=20"
curl -H "X-Stats-Key: wxs_…" "https://webchatix.online/stats-api.php?action=stats&site_key=SITE_KEY"
curl -H "X-Stats-Key: wxs_…" "https://webchatix.online/stats-api.php?action=stats&from=2026-01-01&to=2026-03-31"

{
  "ok": true,
  "account": {"id": 42, "name": "My company"},
  "timezone": "UTC",
  "from": "2026-10-12",
  "to": "2026-10-18",
  "totals": {"unique_visitors": 412, "visits": 530, "page_views": 1874, "bot_hits": 961,
             "form_submits": 23, "chat_messages": 57, "chat_visitors": 14,
             "ads_google": 48, "ads_yandex": 31},
  "days": [
    {"date": "2026-10-18", "unique_visitors": 61, "visits": 74, "page_views": 255, "bot_hits": 140,
     "form_submits": 4, "chat_messages": 9, "chat_visitors": 3,
     "ads_google": 6, "ads_yandex": 4}
  ],
  "sites": [
    {
      "site_key": "SITE_KEY",
      "name": "My site",
      "totals": {"unique_visitors": 300, "visits": 391, "page_views": 1402, "bot_hits": 700,
                 "form_submits": 15, "chat_messages": 40, "chat_visitors": 9,
                 "ads_google": 35, "ads_yandex": 20},
      "days": [ … ],
      "pages": [{"path": "/pricing/", "page_views": 310, "bot_hits": 88, "form_submits": 6}],
      "bots": [{"bot": "Googlebot", "hits": 402}, {"bot": "GPTBot", "hits": 97}],
      "forms": [{"form": "#contact", "submits": 15}]
    }
  ]
}

totals und days sind die Summe über die Websites der Antwort; Besucher werden pro Website gezählt. sites enthält den Bericht jeder Website: days — ein Eintrag pro Datum (Tage ohne Besuche mit Nullen), pages — Top-Seiten (Pfad ohne Query-String) nach Aufrufen plus Bot-Abrufen, bots — Abrufe pro Bot-Name, forms — Absendungen pro Formularname.

POST /stats-api.php?action=hit — serverseitige Hits

Die meisten Such-Bots führen kein JavaScript aus, daher sieht das Widget sie nicht. Um auch sie zu zählen, kann das Backend der Website die empfangenen Anfragen selbst melden: Felder site_key (welche Website des Kontos; Pflicht), url (oder ein Pfad), ua — der User-Agent, optional ip, referrer, visitor_id. Als Paket: {"site_key": "…", "hits": [ … ]}, bis zu 500 Hits pro Anfrage; der site_key eines Hits überschreibt den gemeinsamen. Ob Bot oder Mensch, entscheidet ua.

curl -X POST "https://webchatix.online/stats-api.php?action=hit" \
  -H "X-Stats-Key: wxs_…" -H "Content-Type: application/json" \
  -d '{"site_key": "SITE_KEY", "url": "https://example.com/pricing/", "ua": "Mozilla/5.0 (compatible; bingbot/2.0)", "ip": "203.0.113.7"}'
# → {"ok": true, "views": 0, "bots": 1, "skipped": 0}

Fehler

Gespeichert werden nur Zähler und anonymisierte Besucher-Hashes — keine IPs, Adressen oder User-Agents im Klartext.

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.

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.