Fehlerbehebung und Checkliste

Werkzeuge

• Entwicklerwerkzeuge → Netzwerk: loader.js, core.<hash>.js, die WebSocket-Verbindung (Reiter „Nachrichten“ bzw. „Frames“ zeigt init, init_ok, error) oder die Anfragen des HTTP-Rückfalls (h/auf, …/sse, …/tx).
• Diagnose einschalten: data-rc-debug="true" am Loader-Tag oder in der Konsole localStorage.setItem('rc_debug','1') und neu laden.
• Konsole: ReactiveChat('getSession'), ReactiveChat('getEndpoint'), ReactiveChat('isOpen'), ReactiveChat.version.

Kein Launcher zu sehen

• Site-Key fehlt oder ist ungültig. Der Loader bricht dann still ab. Prüfe data-rc-site-key (8–64 Zeichen aus A–Z a–z 0–9 _ -) am ausgeführten Tag – Tag-Manager und Framework-Helfer lassen Attribute gelegentlich weg.
• type="module" am Script-Tag: Der Loader findet sein Tag dann nicht. Als klassisches Skript einbinden.
• data-rc-hide-launcher="true" oder im Konto „Nur über eigene Links“ eingestellt.
• Keine Markenfarbe im Schnipsel: Ohne gültige data-rc-brand-Farbe erscheint der Knopf erst, wenn die Verbindung steht. Schnipsel aus dem Konto neu kopieren.
• Projekt pausiert oder Site-Key unbekannt: Der Server antwortet mit unknown_site_key (Close 4002); in diesem Tab versucht das Widget es zehn Minuten lang nicht erneut.
• Kern lädt nicht: In der Konsole steht [reactive.chat] core.js …. Häufig blockiert script-src oder ein Werbeblocker die Adresse – siehe Eigene Domain.

Launcher da, aber keine Nachricht kommt an

• Selbst ausgeliefertes loader.js ohne data-rc-ws-url: Das Widget sucht den Chat-Server unter deiner Domain. Im Netzwerk-Reiter siehst du vergebliche Verbindungen zu wss://ws.<deine-domain>/rc_wss/. Lösung: data-rc-ws-url="wss://ws.reactive.chat/rc_wss/".
• origin_denied, Close 1008: Die Domain der Seite fehlt unter Erlaubte Herkünfte. Eingetragen wird die Domain der Website, nicht die Chat-Subdomain.
• CSP blockiert: In der Konsole steht eine CSP-Meldung zu wss://… oder https://…/rc_wss/h/auf. Beide Formen in connect-src aufnehmen.
• Firmennetz ohne WebSocket: Nach zwei gescheiterten Versuchen wechselt das Widget auf den HTTP-Rückfall. Klappt auch der nicht, prüfe Proxys, die Anfragen unter 30 Sekunden abbrechen oder Antworten puffern (Transport).
• Sperre durch den Missbrauchsschutz (Close 1008 blocked): typisch hinter einem eigenen Proxy ohne gültigen Proxy-Schlüssel, weil dann alle Besucher dieselbe Adresse haben.
• Nachricht zu lang: Das Widget sendet Texte über der Tarifgrenze nicht (1000 bzw. 4000 Zeichen).

Angemeldeter Nutzer gilt als anonym

Im Rahmen error steht auth_failed mit detail.reason:

• no_hash – userHash fehlt im identify.
• no_secret – im Projekt ist kein Geheimnis eingerichtet.
• bad_exp – exp in Millisekunden statt Sekunden, oder kein Integer.
• expired – Seite lange offen oder Serveruhr falsch; Hash beim Laden der Seite frisch berechnen.
• exp_too_far – mehr als 24 Stunden voraus.
• bad_hash – Geheimnis, Reihenfolge (userId + "." + exp) oder Zeichensatz stimmen nicht; das Geheimnis ist als Zeichenkette der Schlüssel, nicht als dekodierte Bytes. Mit E-Mail muss sie genau so signiert sein, wie du sie übergibst.

Details: Besucher identifizieren.

Kundendaten kommen nicht an

• Assistent bittet um Anmeldung, obwohl der Nutzer angemeldet ist: exp fehlt oder ist abgelaufen – ohne exp gibt es keine Kundendaten.
• Verbindung testen im Konto nennt den Grund (http_401, zeitueberschreitung, umleitung, adresse_privat …). Signiert wird X-RC-Zeit + "." + roher Body – prüfe gegen die ankommenden Bytes, nicht gegen neu kodiertes JSON.
• Ein Feld fehlt in der Antwort des Assistenten: im Konto nicht freigegeben, oder es steht auf der Liste der nie übernommenen Felder.

Details: Kundendaten-Endpunkt.

Webhooks kommen nicht an

• Integration eingeschaltet, Ereignis ausgewählt (keine Auswahl = alle)? Nach dem Einschalten bis zu 15 Sekunden warten.
• Dein Endpunkt antwortet länger als 10 Sekunden oder mit einer Weiterleitung.
• Dein Endpunkt hat einmal 410 geantwortet – das deaktiviert die Integration. Wieder einschalten.
• Signatur passt nicht: über den rohen Body und X-RC-Timestamp + "." + Body rechnen, Präfix sha256= beachten.
• Inhalte fehlen in data: welche Felder je Ereignis kommen, steht unter Webhooks; ein abgeschaltetes Ereignis kommt gar nicht.

Server-API

• 401 auth_failed: Schlüssel widerrufen, vertippt, oder die Person, die ihn angelegt hat, ist nicht mehr Admin.
• 403 insufficient_scope: Rechtestufe reicht nicht; required_scope nennt die nötige.
• 429: 120 Anfragen je Minute überschritten; Retry-After beachten.
• 415/413: Content-Type: application/json fehlt bzw. Rumpf über 64 KiB.

Datenschutztext erscheint nicht

• Der Loader fehlt auf der Seite oder wird von der Consent-Plattform blockiert: datenschutz.js direkt einbinden.
• Die Website ist nicht als Domain im Projekt eingetragen, oder das Projekt ist pausiert.
• data-rc-privacy-state="error" am Element zeigt einen gescheiterten Abruf.

Checkliste vor dem Livegang

1. Alle Domains der Website unter Erlaubte Herkünfte eingetragen.
2. Schnipsel aus dem Konto unverändert auf allen Seiten, auf denen der Chat erscheinen soll – auch auf der Datenschutzseite.
3. CSP: script-src Auslieferungsort, connect-src mit wss:// und https://, img-src für Bilder.
4. Einwilligung: data-rc-consent oder Consent-Plattform (TCF v2 / consented.eu) geprüft – mit und ohne Zustimmung getestet.
5. Datenschutzerklärung ergänzt (<div data-rc-privacy> oder Textbaustein).
6. Identität: userHash mit exp auf dem Server berechnet, Geheimnis nur in der Serverumgebung, init_ok.identity.verified ist true.
7. Bereiche mit vertraulichem Text mit data-rc-private markiert.
8. Bei eigener Domain: alle fünf Prüfschritte „in Ordnung“, Proxy-Schlüssel nur in der Proxy-Konfiguration, /rc_wss/h/ nicht im Zugriffsprotokoll.
9. Webhooks: Signatur und Zeitstempel geprüft, Doppelte über X-RC-Delivery erkannt, schnelle 2xx-Antwort.
10. HTTP-Rückfall einmal mit data-rc-transport="http" getestet.
11. Mobile Ansicht (unter 480 Pixel öffnet der Chat im Vollbild) und Tastaturbedienung geprüft.