Troubleshooting

Find your symptom below. For a missing widget, work through the checks in order; the first one that fails is almost always the cause.

Quick reference

Symptom	Most likely cause
No chat button, and POST /widget/session returns 401	The page’s hostname isn’t in your allowed domains, or the site key is wrong
widget.js returns 404	The script src doesn’t point at https://widget.agentmysite.com/loader/widget.js
Session returns 200, but the chat window is blank or missing	data-iframe-origin is missing or wrong, or a Content Security Policy blocks the frame
Works on one domain but not another	The other hostname isn’t in your allowed domains (www and the bare domain are different)
The chat button appears, then nothing happens	Mixed content, or a Content Security Policy blocks the API or the frame
Message box disabled, “Assistant unavailable”	Your credits for the period are used up
“I can’t help with that” style answers	The content that answers the question is missing or not Ready

The chat button doesn’t appear

Open your page, then open your browser’s developer tools and select the Network and Console tabs. Reload the page.

1. Check the loader

Filter Network for widget.js.

• 200: the loader is fine. Go to the next check.
• 404 or no request: check that the snippet’s src is exactly https://widget.agentmysite.com/loader/widget.js, and that the snippet is on this page. Copy it again from Site Settings > Site key & embed snippet.

2. Check the session request

Filter Network for session. The widget calls POST https://api.agentmysite.com/widget/session when it starts.

Status	Meaning	Fix
401	The page’s hostname isn’t in your allowed domains, or the site key doesn’t exist. The widget shows nothing.	Find the Origin request header, for example https://shop.acme.com. Add its hostname, shop.acme.com, in Site Settings > Allowed domains. Check that data-site-key matches the key in Site Settings exactly.
429	Too many sessions were started in a short time.	Wait a minute and reload.
Failed, CORS or blocked	data-api-base is wrong, or the page is https and the API address is http.	Use data-api-base="https://api.agentmysite.com", as in your snippet.
200	The session is fine.	Go to the next check.

Tip

Allowed domains are hostnames only. Ports are ignored, so localhost covers every local port. www.acme.com and acme.com are different; add both if visitors use both.

Note

For an embedded Shopify app, the page’s hostname is your app’s own domain, such as your-app.fly.dev, not admin.shopify.com.

3. Check the chat window

Look in Network for a request to https://widget.agentmysite.com/iframe/.

• Missing, or sent to api.agentmysite.com: data-iframe-origin is missing or wrong. When it’s missing, the widget tries to load the chat window from the API host, which fails silently. Set data-iframe-origin="https://widget.agentmysite.com", or copy the full snippet again.
• 200, but blank: check the Console for Content Security Policy errors (next check).

4. Check your Content Security Policy

If your site sends a Content-Security-Policy header, the Console shows lines starting with Refused to load, Refused to connect or Refused to frame. Allow these sources:

Content-Security-Policy

script-src  'self' https://widget.agentmysite.com;
connect-src 'self' https://api.agentmysite.com;
frame-src   https://widget.agentmysite.com;

A missing connect-src is the most common cause of a widget that fails silently.

5. Check that the button isn’t hidden

In the Elements tab, search for agentmysite-widget-iframe.

• Not found: the widget stopped at an earlier check. Go back to checks 1 to 4.
• Found, but you can’t see it: your page’s CSS is covering it. The widget is fixed to the bottom-right corner. Look for an element with a higher z-index in that corner, or a parent with overflow: hidden or a transform.

Test from the console

Paste this into the browser console on your page, with your site key, to test the session directly:

fetch("https://api.agentmysite.com/widget/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ siteKey: "YOUR_SITE_KEY" }),
}).then((r) => r.json().then((j) => console.log(r.status, j)));
// 200 and a token: the session works; check the chat window and CSP
// 401: add this page's hostname to Allowed domains, or check the site key

Chat history doesn’t persist

Inside some embedded frames and in private browsing, the browser blocks storage. The widget still works, but it can’t remember the visitor between page loads, so history starts fresh after a reload.

The assistant is paused

If the message box is disabled with the placeholder Assistant unavailable, your account has used all its credits for the period. Check Dashboard > Plan & usage. See Credits and billing.

Answers aren’t what you expect

• The assistant says it can’t help. It only answers from your content. Check that a page or document covers the question and that its status is Ready on the Documents page. The question also appears on the Unanswered page.
• Answers are out of date. Re-sync changed web pages, and replace changed documents. See Keep content fresh.
• A document failed. Read the reason under its name on the Documents page. See Fix a failed document.
• A web page has little useful text. Pages that need a login or build their text with JavaScript may not have readable text. Upload the content as a document instead.

To see which sources an answer used, open the conversation in Conversations and select Show N sources under the reply.

Visitors send too many messages

To protect your credits from abuse, each visitor can send up to 20 messages in 10 minutes, and each site up to 200 messages in 10 minutes. A message can be up to 2,000 characters.

Still stuck?

Email support@agentmysite.com with your site name, the page address, and a screenshot of the Network tab.