Skip to content
Sam Docs

Troubleshooting Sam install

The most common reasons the Sam widget doesn’t appear after install, ordered by frequency.

”I installed the widget but it doesn’t appear”

1. Cache

This catches almost everyone. Many CMSs and CDNs cache HTML for hours. Even after you save, your visitors (and you, in your normal browser) get the old cached version.

Fix: clear your site’s cache. Then hit your site in an incognito window (no caching), or in a different browser. If the widget appears in incognito but not in your normal browser, it’s a cache issue.

Common culprits:

  • WordPress: WP Rocket, W3 Total Cache, LiteSpeed Cache, Cloudflare’s “Cache Everything” rule
  • Shopify: rare on Shopify itself, but if you use Cloudflare in front, purge there too
  • Wix / Squarespace: their built-in CDNs cache for ~5 minutes — wait or hit it from incognito
  • Static sites: re-deploy after editing the layout file

2. You didn’t publish

  • Webflow → click Publish in the Designer
  • GTM → click Submit AND Publish
  • Wix → click Publish in the Wix Editor

Saving changes is not the same as publishing.

3. Wrong API token

If the widget loads but won’t connect (you might see “Invalid API key” in the browser console, or it just shows nothing), the token is wrong.

Fix: copy the token from your Sam dashboard again. Tokens are 40 alphanumeric characters — make sure no extra spaces or quote marks crept in.

4. Content Security Policy

If your site has a strict CSP header, it can block scripts from cdn.viasam.app.

Fix: add https://cdn.viasam.app to script-src and https://viasam.app to connect-src in your CSP. Open browser dev tools (F12) → Console — CSP violations are logged loudly.

5. Allowed origins doesn’t match your site URL

In your Sam dashboard you can restrict which domains the widget runs on (the Allowed origins field on each widget). If your site URL isn’t on that list (and the list isn’t empty), the widget refuses to connect.

Fix: open your widget settings and either add your domain to Allowed origins, or clear the list to allow any origin.

”Widget appears but visitors can’t send messages”

Open browser dev tools → Network tab → filter for viasam.app and try sending a message. Look at the response:

  • 401 / 403: API token issue, or the request origin isn’t on your widget’s Allowed origins list.
  • 410: your widget is paused (usually because of plan downgrade — check your Sam billing page).
  • 429: rate limited. The widget retries automatically; usually clears in a minute.
  • No request at all: the widget script never loaded. Re-check the install steps.

”Widget appears on some pages but not others”

Almost always the snippet is on one specific page rather than the site’s shared layout/footer. Move it to the layout/footer file (or, in CMSs, the global “Footer” code injection) so it shows on every page.

GTM exception: if you set the trigger to a specific page-view trigger instead of All Pages, that’s why. Edit the tag → Triggering → All Pages.

”Verify says ‘not detected’ but the widget works”

This happens with single-page apps and GTM-injected installs — the widget script isn’t in the initial HTML response, so our HTML scan doesn’t find it.

The verifier has a fallback: it checks whether your widget has been seen “live” in the last 5 minutes. If you open your site in a new tab so the widget loads at least once, then come back and click verify, it’ll switch to “Widget is live.”

Still stuck?

Email support@viasam.app. Include:

  • The URL of your site
  • The name of the widget you installed
  • A screenshot of your browser’s dev tools Console + Network tabs after reloading the site

We usually respond within a few business hours.