Troubleshooting
Use this page when Visitor SDK appears in the dashboard but does not behave as expected on the real client website.
Domain first
Most browser failures are allowed-domain or Origin mismatch issues.
Command path
Use Open Chat to prove the SDK command can open support.
Refresh
After changing services or domains, refresh the SDK and reload the website.
Mobile
Final go-live testing should include a real phone browser.
Common issues
SDK_ORIGIN_NOT_ALLOWED
Symptom: The SDK loads in dashboard but fails on the client website.
Check: Run bootstrap with the same Origin as the client website.
Fix: Add the exact website domain in Dashboard > Developer > Visitor SDK, then refresh the client page.
SDK_CLIENT_NOT_FOUND
Symptom: Bootstrap returns tenant not found.
Check: Confirm the slug or Public Widget Key is copied from the correct tenant.
Fix: Use the logged-in tenant slug from dashboard docs links, or replace the placeholder slug with the tenant you are testing.
FEATURE_NOT_AVAILABLE
Symptom: Chat, Voice, Video, or AI does not open.
Check: Inspect bootstrap services and statuses.
Fix: Check active subscription, plan-contract entitlement, admin service toggles, and service setup.
ai_not_ready
Symptom: AI Chat or AI Voice is hidden or blocked.
Check: Confirm AI readiness and knowledge indexing in the dashboard.
Fix: Finish AI setup before exposing AI routes to visitors.
Floating button visible, support window does not open
Symptom: The launcher appears, but clicking it does not show support.
Check: Open browser console and Event Log in Dashboard Runtime SDK Test.
Fix: Use Open Chat to verify the command path. If it works in dashboard but not website, recheck allowed domain and client-side script errors.
Dashboard Runtime Test feels invisible
Symptom: Clicking Headless or Open Chat only writes events in the log.
Check: Headless mode intentionally prepares the SDK without showing a launcher.
Fix: Use Open Chat, Open Voice, or Open Video to validate commands; use the client website for final visual testing.
Mobile open/close issue
Symptom: Support opens on desktop but feels cramped or hard to close on phone.
Check: Test in a real mobile browser, not only desktop responsive mode.
Fix: Validate touch target, close action, page scroll, and keyboard behavior before go-live.
Origin check
Replace client-domain.com with the real website domain. If this returns SDK_ORIGIN_NOT_ALLOWED, fix allowed domains first.
curl -H "Origin: https://client-domain.com" \ "https://api.ringnity.com/api/sdk/bootstrap?slug=your-tenant-slug&debug=true"
Expected successful events
When Chat opens correctly, a simple command flow usually logs:
onReady onServiceSelected chat onOpen chat
Need the whole go-live flow? Open Launch checklist.