Troubleshooting & FAQ
Solutions to common issues: widget not appearing, invalid origins, auth errors, and more.
The widget doesn't appear.
Check the browser console for errors, confirm workspaceId/widgetId, and that
your page's origin is in the widget's allowed origins. The GET /config
call must succeed.
invalid_origin when starting a session.
Add your site's exact origin (scheme + host + port) to the widget's allowed
origins. Wildcards are single‑label (https://*.customer.com matches
app.customer.com but not a.b.customer.com).
auth_required / auth_expired for logged‑in users.
Ensure tokenProvider returns a valid JWT signed with the widget secret and
including sub, widget_id, workspace_id, and a future exp. The SDK
refreshes automatically; a thrown tokenProvider surfaces as error.
Agent replies don't appear in real time.
Confirm the page can reach the API over HTTPS and WebSocket
(wss://). Corporate proxies sometimes block WebSocket; the widget falls back
but with slightly higher latency.
Conversations from before login disappeared.
Use identify() (not a fresh boot with a new user) to merge anonymous
history. Ensure allowAnonymousToIdentifiedMerge is enabled.
Multiple users on one browser see each other's chats.
Call shutdown({ clearStorage: true }) on logout.
How do I theme it to match my brand?
Set theme in window.SupportChatSettings (or SupportChat.createChat), call
setTheme(...) at runtime, or set defaults in the workspace admin.