Widget troubleshooting - Open.cx Docs

Before debugging, have these ready: the page where the widget is embedded, the widget mode you are using (HTML, React, or headless), the identity model you chose, and one recent conversation if possible.

Looking for setup guidance? See Install Widget, Mobile Support, Authentication, and Conversation Sessions.

Can’t reproduce a styling or option issue locally? Open the Playground to run the widget in isolation with a known-good config and compare behavior.

Common Troubleshooting Scenarios

Symptom	Likely cause	What to do
Widget does not appear	Missing script, wrong widget token, or the widget is mounted in the wrong place	Re-check the embed snippet, confirm the widget token from your OpenCX dashboard, and verify whether you intended a floating or inline embed.
Visitor is asked for details again or cannot see earlier chats	The widget is using an anonymous or non-verified identity, or browser storage was reset	Decide whether the visitor should stay anonymous, use `collectUserData`, or receive a verified `user.token`. If history must work across devices, use server-side authentication.
Signed-in customer still cannot see the right history	The widget is using `user.data` instead of `user.token`, or history should be scoped with `externalId`	Verify that your backend is calling `/widget/authenticate-user`, then pass the returned token as `user.token`. If the same email can belong to multiple accounts, add `externalId`.
Custom action result shows as plain text instead of your UI	The component key does not match the action `operation_id`, or your headless renderer is not branching on the right action name	Re-check the component mapping, confirm the action name, and make sure your component has a fallback state for missing payload data.

Most widget issues come from one of three places: the embed path, the visitor identity model, or custom rendering logic. Start there before assuming the problem is in the AI itself.

Identity And History Checklist

Work through these in order if history is the problem:

Check whether the visitor is anonymous, non-verified, or verified.
Confirm whether your app is passing user.data or user.token.
Decide whether cross-device history is actually required.
Add externalId if one person can belong to multiple accounts or workspaces.
Retest with the same browser and then with a second device.

Expectations And Limits

Area	Detail
Returning history	Newest conversations appear first when history is available for that identity.
Resolved sessions	Resolved sessions remain in history, but they are not active chat threads.
File uploads	Files larger than 5 MB are rejected.
Custom UI	If your custom renderer does not match the action name or payload, the widget falls back to normal message rendering or your own fallback logic.

Install Widget

Re-check your embed path, token, and launcher mode.

Authentication

Fix identity mismatches and cross-device history problems.

Conversation Sessions

Re-check how history, resolution, and handoff should behave.

Mobile Support

Re-check WebView, identity, and mobile support setup.

​Common Troubleshooting Scenarios

​Identity And History Checklist

​Expectations And Limits

​Related Documentation

Install Widget

Authentication

Conversation Sessions

Mobile Support

Common Troubleshooting Scenarios

Identity And History Checklist

Expectations And Limits

Related Documentation