FAQ / Troubleshooting
FAQ & Troubleshooting
When something breaks in Supportly, isolate the layer first: embed and transport, workspace configuration, AI and knowledge quality, or operator permissions. Most issues become obvious once the failing layer is clear.
Frequently asked questions
- 1
Why is the widget not appearing?
Verify that the widget script loads successfully, the workspace key is valid, and the widget config endpoint returns a success response.
- 2
Why is the AI answering too vaguely?
Tighten the system prompt, add better FAQs, and review whether the uploaded source material is too broad or stale.
- 3
Why can an agent not update a ticket?
Check the operator role, workspace membership, and whether the correct x-workspace-id context is being used.
- 4
Why are invitations failing?
Make sure the invite email matches the account email the user signs in with, and check whether the invitation has expired.
Recommended diagnostic flow
| Symptom | Check first | Likely root cause |
|---|---|---|
| Widget does not load | GET /api/widget/config/[apiKey] | Invalid key, bad embed path, or config failure |
| Streaming is inconsistent | WS URL and fallback chat route | Realtime transport issue or host-network policy |
| Answers are wrong | Prompt plus KB content | Weak instructions or poor retrieval source material |
| Operator cannot access resource | Membership and role | Permission mismatch or wrong workspace context |
| Notifications seem missing | Preference settings and trigger path | Muted preference or untriggered workflow |
When to escalate internally
Escalate to your internal engineering owner when the issue crosses from product behavior into platform behavior: broken uploads, invalid auth state, repeated build failures, or route-level server errors.
Escalate to support operations when the issue is policy or content driven: bad system prompt boundaries, poor FAQ coverage, or misconfigured handoff rules.
Useful issue report template
1Workspace:2Page or route:3Customer-visible symptom:4Expected behavior:5Actual behavior:6API endpoint or UI surface involved:7Conversation or ticket ID:8Recent config changes:9Screenshots or payload samples: