Troubleshooting

Why: The console says [Daneshyar] widget.js needs data-api-key, data-app-id and data-workspace-id, or widget.js did not load at all.

Fix: Check that all three attributes are on the same script tag and are not empty. An environment variable that was not set at build time is empty. Check the src address in the Network tab.

Why: Inline mode needs an element to fill, and the script ran before that element existed, or the selector is wrong.

Fix: Add <div id="daneshyar-widget"></div> above the script tag, or set data-target to your own selector.

Why: The chat opened, but it got no API key.

Fix: Check that data-api-key has a value. In a framework, check that the environment variable is available in the browser (for example the NEXT_PUBLIC_ or VITE_ prefix).

Why: Your site is not in the app's allowed domains. The list belongs to the whole app, so it covers every workspace you embed. Remember that *.clinic.ir does not match clinic.ir, and that localhost:5173 does not match localhost:3000.

Fix: In the console, open the Embed page and add the exact host you see in the address bar.

Why: Your own site sends a Content-Security-Policy that does not allow the widget's site.

Fix: Add the widget's site (the address in the snippet's src) to script-src and frame-src in your policy.

Why: The widget could not load its settings. Usually the key is wrong (403) or the workspace id does not belong to this app (404).

Fix: Copy the snippet again from the Embed page of the right workspace. If the ids are right, try again in a minute: it may be a network problem.

Why: A rate limit was reached: 20 questions an hour from one IP address, or 500 a day for the whole app.

Fix: Wait and try again. Many people behind one office network share one IP address. If you need higher limits, contact us.

Why: The account that owns the app has run out of credits (402). Visitors never see a billing message.

Fix: Add credits to the owner's account in the console.

Why: The workspace has no documents, or none of them is ready yet.

Fix: Upload documents in the console and wait until their status is Ready.

Why: This is by design. The widget answers only from the workspace's documents and politely declines everything else.

Fix: Ask about something your documents cover, or add a document that answers it.

Why: In a single-page app, the script was added inside a page component, or in two places.

Fix: Load it once, in the root layout or root component. See Framework guides.

Why: The console cannot save an empty list yet.

Fix: Contact us to clear the list. Until then, keep at least one domain in it.

Why: The X-API-Key header is missing, or the key does not match any app. A missing or wrong key returns 403, not 401.

Fix: Send the header on every request, with no spaces or line breaks around the key. Check that your server reads the right environment variable.

Why: The workspace id is wrong, the workspace was deleted, or it belongs to a different app. A key only sees its own app's workspaces, and it gets 404 for any other.

Fix: List your workspaces with GET /v1/workspaces/, using the same key, and use an id from that list.

Why: The request body is not valid, for example external_user_id is missing in a chat request.

Fix: Read the message field in the response: it names the field and the problem.

Why: The account that owns the app has run out of credits.

Fix: Add credits in the console, then send the request again.

Why: Your website's JavaScript is calling /v1 directly. The API does not allow that, and it would expose your key.

Fix: Call the API from your server instead. See Security.

Why: A short problem on our side or on the network. An answer can take several seconds, because it reads your documents first.

Fix: Use a timeout of at least 60 seconds for chat requests. Retry 5xx errors after a short wait, and do not retry 4xx errors.