Troubleshooting and checklist

Tools

• Developer tools → Network: loader.js, core.<hash>.js, the WebSocket connection (the “Messages” or “Frames” tab shows init, init_ok, error) or the requests of the HTTP fallback (h/auf, …/sse, …/tx).
• Switch on diagnostics: data-rc-debug="true" on the loader tag or localStorage.setItem('rc_debug','1') in the console, then reload.
• Console: ReactiveChat('getSession'), ReactiveChat('getEndpoint'), ReactiveChat('isOpen'), ReactiveChat.version.

No launcher visible

• Site key missing or invalid. The loader then aborts silently. Check data-rc-site-key (8–64 characters from A–Z a–z 0–9 _ -) on the executed tag – tag managers and framework helpers occasionally drop attributes.
• type="module" on the script tag: the loader then cannot find its tag. Embed it as a classic script.
• data-rc-hide-launcher="true", or “Only via your own links (no chat icon)” set in your account.
• No brand colour in the snippet: without a valid data-rc-brand colour, the button only appears once the connection is up. Copy the snippet from your account again.
• Project paused or site key unknown: the server responds with unknown_site_key (close 4002); in this tab the widget does not try again for ten minutes.
• Core does not load: the console shows [reactive.chat] core.js …. Often script-src or an ad blocker blocks the address – see Own domain.

Launcher there, but no message arrives

• Self-hosted loader.js without data-rc-ws-url: the widget looks for the chat server under your domain. In the network tab you see futile connection attempts to wss://ws.<your-domain>/rc_wss/. Solution: data-rc-ws-url="wss://ws.reactive.chat/rc_wss/".
• origin_denied, close 1008: the page's domain is missing under Allowed origins. Enter the website's domain, not the chat subdomain.
• CSP blocks: the console shows a CSP message about wss://… or https://…/rc_wss/h/auf. Add both forms to connect-src.
• Corporate network without WebSocket: after two failed attempts, the widget switches to the HTTP fallback. If that does not work either, check for proxies that abort requests in under 30 seconds or buffer responses (Transport).
• Block by the abuse protection (close 1008 blocked): typical behind your own proxy without a valid proxy key, because all visitors then have the same address.
• Message too long: the widget does not send texts above the plan limit (1000 or 4000 characters).

Signed-in user counts as anonymous

The error frame contains auth_failed with detail.reason:

• no_hash – userHash is missing in identify.
• no_secret – no secret has been set up in the project.
• bad_exp – exp in milliseconds instead of seconds, or not an integer.
• expired – page open for a long time or wrong server clock; compute the hash freshly when the page loads.
• exp_too_far – more than 24 hours ahead.
• bad_hash – secret, order (userId + "." + exp) or character set do not match; the secret is the key as a string, not as decoded bytes. With an email address, it must be signed exactly as you pass it.

Details: Identifying visitors.

Customer data does not arrive

• The assistant asks the user to sign in although they are signed in: exp is missing or has expired – without exp there is no customer data.
• Test connection in your account names the reason (http_401, zeitueberschreitung, umleitung, adresse_privat …). The signed string is X-RC-Zeit + "." + raw body – verify against the bytes as received, not against re-encoded JSON.
• A field is missing in the assistant's answer: it is not enabled in your account, or it is on the list of fields that are never taken over.

Details: Customer data endpoint.

Webhooks do not arrive

• Integration switched on, event selected (no selection = all)? After switching on, wait up to 15 seconds.
• Your endpoint takes longer than 10 seconds to respond, or responds with a redirect.
• Your endpoint once responded with 410 – that deactivates the integration. Switch it on again.
• Signature does not match: compute over the raw body and X-RC-Timestamp + "." + body, mind the sha256= prefix.
• Content missing in data: which fields each event carries is listed under Webhooks; an event that is not selected does not arrive at all.

Server API

• 401 auth_failed: key revoked, mistyped, or the person who created it is no longer an admin.
• 403 insufficient_scope: the scope is not sufficient; required_scope names the one needed.
• 429: 120 requests per minute exceeded; respect Retry-After.
• 415/413: Content-Type: application/json missing, or body over 64 KiB.

Privacy text does not appear

• The loader is missing on the page or is blocked by the consent platform: embed datenschutz.js directly.
• The website is not entered as a domain in the project, or the project is paused.
• data-rc-privacy-state="error" on the element indicates a failed request.

Checklist before going live

1. All domains of the website entered under Allowed origins.
2. Snippet from your account unchanged on all pages where the chat should appear – including the privacy page.
3. CSP: script-src delivery location, connect-src with wss:// and https://, img-src for images.
4. Consent: data-rc-consent or consent platform (TCF v2 / consented.eu) checked – tested with and without consent.
5. Privacy policy extended (<div data-rc-privacy> or text block).
6. Identity: userHash with exp computed on the server, secret only in the server environment, init_ok.identity.verified is true.
7. Areas with confidential text marked with data-rc-private.
8. With your own domain: all five check steps “OK”, proxy key only in the proxy configuration, /rc_wss/h/ not in the access log.
9. Webhooks: signature and timestamp verified, duplicates detected via X-RC-Delivery, fast 2xx response.
10. HTTP fallback tested once with data-rc-transport="http".
11. Mobile view (below 480 pixels the chat opens full screen) and keyboard operation checked.