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.dataoruser.token. - Decide whether cross-device history is actually required.
- Add
externalIdif 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. |
Related Documentation
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.
Custom Components
Re-check action mapping and advanced widget UI behavior.