Widget troubleshooting

This page covers the most common issues with the chat widget itself. For account or dashboard issues, see Dashboard troubleshooting.

Check in this order:

Open the browser console. Errors with “Sam” or “viasam” in the message tell you the cause directly.
Verify the install snippet is on the page. Right-click → View page source, search for widget.js. If it’s missing, your CMS may have stripped it — see your install guide.
Check allowed origins. In the Widget Editor, open your widget and check the allowed origins list includes the exact domain you’re testing on (with the right protocol — https:// vs http://, with or without www.).
Make sure the widget is active. A paused widget (after a plan downgrade) won’t load. Open the widget in the dashboard and check the status.

I see a CORS error in the console

CORS errors mean the domain in the browser doesn’t match the allowed origins on your widget. Add the exact origin to your widget’s allowed origins list. Origins are scheme + host + port — https://example.com and https://www.example.com are different origins.

I see a Content Security Policy (CSP) error

Sites that use a strict CSP need to allow the Sam domains. Add the following to your CSP header:

script-src https://widget.viasam.app;
connect-src https://api.viasam.app;
img-src https://cdn.viasam.app;
style-src https://widget.viasam.app 'unsafe-inline';

Adjust to match your site’s CSP style — these are the directives Sam needs.

Colours don’t match what I set

Two common causes:

Edge cache. The widget config caches at our CDN for up to 5 minutes. Wait, then hard-refresh (Ctrl+Shift+R / Cmd+Shift+R).
Site CSS overriding widget. Some sites have global CSS that targets generic class names. Sam’s widget runs in a Shadow DOM by default to prevent this, but on some legacy browsers it can leak. If you see your site fonts inside the widget, check Reduce → site CSS overriding widget — usually a global * { … } rule.

Knowledge base may be empty or still indexing. Check Knowledge Base — every file should be in Uploaded state, not Pending or Failed.
Conversation cap reached. Check Billing — if you’re at your monthly cap, new conversations may be rejected.
Trial expired. Trial widgets stop replying after 7 days.

Sam gives wrong or weird answers

Sam can only answer with what’s in:

The Knowledge Base files for that widget (filtered by tags if set)
The system prompt override

If answers are wrong, fix in this order:

Check tags. If your widget has knowledge tags set, only files with matching tags are read. Bad tagging leads to “I don’t know” answers.
Check the system prompt. A prompt that says “Always answer in three sentences” can override what visitors actually want.
Check knowledge file freshness. Old or outdated files in the Knowledge Base will mislead Sam. Replace them.
Check the model. On Trial and Starter, Sam uses gpt-4o-mini only. Upgrade to Growth or Pro to use gpt-4o for better reasoning.

For nuanced replies (style, tone, personality), use system prompt override.

Below 480px viewport width, the widget opens full-screen automatically. This is by design — mobile chat usability suffers in tiny floating panels. There’s no setting to disable this.

Visitors are seeing the wrong language

Each widget is locked to one language. Check Widget Personality — the language dropdown determines what Sam speaks regardless of the visitor’s browser language.

For multi-language sites, run one widget per language and use your site’s locale logic to embed the right one.

The launcher button is hidden behind another element

The launcher uses z-index: 2147483000 (very high). If something on your site is still on top, your site has a CSS stacking context conflict. Wrap your competing element in a position: relative ancestor, or contact us — we can suggest a workaround.