# Troubleshooting

> Fix the most common problems with the AgentMySite widget, from a missing chat button to unexpected answers.

Source: https://agentmysite.com/docs/guides/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. |

<Aside type="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.
</Aside>

<Aside type="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`.
</Aside>

### 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:

```text title="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:

```js
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](/docs/guides/credits-and-billing/#at-100-the-assistant-pauses).

## 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](/docs/guides/content/keep-content-fresh/).
- **A document failed.** Read the reason under its name on the **Documents** page. See [Fix a failed document](/docs/guides/content/upload-documents/#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](mailto:support@agentmysite.com?subject=Widget%20troubleshooting) with your site name, the page address, and a screenshot of the **Network** tab.