Troubleshooting

Use this page when the widget is installed but does not behave as expected.

Widget Does Not Appear

Check the browser console first. ChattyBox reports missing required attributes there.

Common causes:

• The script is absent from both the deployed HTML and the live DOM.
• The script was added to the wrong template, layout, tag manager container, or CMS code area.
• The script is behind a consent rule or tag manager trigger that did not fire.
• The application component that mounts the loader never runs on that route.
• A Content Security Policy blocks https://chattybox.ai/widget.js.
• CSS or another widget overlaps the launcher.
• The deployed configuration has widget.enabled: false.

Smallest fix:

1. Open the deployed public page in an incognito window.
2. Search page source and the browser's Elements panel for chattybox.ai/widget.js; an SDK- or JavaScript-injected loader may appear only in the live DOM.
3. Confirm the script appears once and includes data-api-key and data-api-url.
4. Move the script to the global footer, app layout, Docusaurus root, or GTM All Pages trigger if it is missing.

For config-managed projects, widget.enabled: false prevents the hosted widget from initializing and makes public POST /chat requests return 403 Widget is disabled, including headless SDK requests. Change that setting through the config deployment workflow, not by rotating the public key. Removing a loader script after initialization does not remove the already rendered widget.

Missing data-api-url

The widget exits early when data-api-url is missing.

Use the full snippet from the dashboard or add the required attribute:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

Use the API URL from your dashboard instead of guessing. In production, it is expected to be a stable https://...convex.site/chat URL.

Generic 401 Invalid API key

For security, widget API endpoints return the same generic 401 Invalid API key response for an unknown, expired, or origin-rejected public key. Do not rely on the response to identify the cause.

Common causes:

• The public widget key was copied incorrectly.
• The key was deleted, expired, or copied from a different backend deployment than the API URL.
• The key's project or owner is being deleted.
• Optional origin restriction is enabled for the key and the current site origin is not included.

Fixes:

1. Open the project in the ChattyBox dashboard.
2. Copy a fresh snippet from the Embed tab.
3. Check Public Keys > Edit origins only if Restrict this key to specific origins is enabled. Add the exact origin that serves the page, or disable the optional restriction. Scheme, hostname, and port must all match: https://example.com, https://preview.example.com, and http://localhost:3000 are different origins. Paths do not need separate entries.
4. Redeploy or republish the site and test again in an incognito window.

A valid key for another chatbot on the same backend normally selects that chatbot rather than producing a 401; check the project if answers are unexpectedly unrelated. Key names such as "production" and "staging" do not enforce environments. The HTTP API uses Origin, falling back to the origin of Referer; a restricted key rejects requests without a matching origin from either header. Origin restrictions are not a substitute for visitor authentication.

Message Limits or Rate Limits

Check Account & Billing at /settings/account for message usage, plan, and optional Pro/Business PAYG budgets. Test Chat and public chat both consume the owner's shared message allowance. Deleting conversations or creating another key does not reset that allowance.

Monthly allowance errors and short-term request rate limits are different. For HTTP 429 responses, honor Retry-After when supplied instead of repeatedly retrying. For a monthly message-limit error, wait for the allowance to reset or adjust the plan/eligible PAYG budget. The Logs tab is conversation history, not a per-request error console; use the browser Network panel to inspect HTTP failures.

Wrong Language

First check Embed > Widget Language (also available in the project's Settings). The hosted widget chooses its UI language in this order:

1. data-locale on the widget script, only if Allow script override is enabled.
2. In Fixed mode, the configured default language.
3. In Auto-detect mode, the page <html lang> value, then the browser language if no page language exists, then the configured default if neither exists.

Unsupported locale values normalize to English. An unsupported but present page language does not cause the widget to try the next candidate. The configured default starts as English.

Fixes:

• For automatic language selection, choose Auto-detect and remove an incorrect data-locale or disable script overrides.
• Set <html lang="de">, <html lang="fr">, or the matching supported language code on localized pages.
• To force the configured language, choose Fixed and disable Allow script override. With overrides enabled, data-locale still takes priority over Fixed mode.
• Save the settings, reload the installed widget, and test again. Locale is resolved at initialization, not on every client-side route change. A locale supplied to mountWidget() becomes data-locale and follows the same rules.
• Check for a failed /widget-config request if saved language settings are ignored. On a config-fetch failure the loader continues with defaults rather than the project's saved locale policy.
• Index each required language version if answers cite or retrieve content from the wrong language. The answer generator detects language from the question, separately from widget UI locale; Fixed widget language does not force answer language or translate source content. The default enforced missing-content fallback is English unless separately configured through config as code.

No Citations or Weak Answers

ChattyBox answers from indexed content. Missing citations or weak answers usually mean the needed source content was not retrieved or does not clearly answer the question.

A reliable grounded RAG chatbot needs clear retrieved source content for every answer it gives.

Fixes:

• Ask the same question in the dashboard test chat and compare the cited pages.
• Make sure the source page is public and included in the crawl.
• Add clear headings, examples, FAQs, and direct answer text to the source page.
• Avoid relying on screenshots, videos, excluded hidden markup, JavaScript-only content, or iframes as the only source.
• Re-scrape the updated page when the cooldown allows it, wait for embedding work, then test again.
• Look for Partially indexed warnings; text beyond the 512 KiB per-page limit is not retained. Split long source pages rather than repeatedly rebuilding the same truncated text.
• Make each question self-contained. Saved conversation history is not currently included in the answer generator's prompt.

Persona adds site-specific instructions to built-in grounding rules; it cannot supply missing indexed content or replace the enforced missing-context/content-gap fallback. That fallback has a separate assistant.fallbackMessage setting in configuration as code.

Pages Not Scraped or Stale Content

Common causes:

• The page is missing from the submitted sitemap.
• Manual URL mode did not include the page.
• The page blocks ordinary HTTP fetches, requires authentication, returns a CAPTCHA/error page, or redirects to a blocked target.
• The page content changed after the last scrape.
• The content is only rendered by JavaScript, or is outside the selected semantic content root.
• The selected URLs exceeded the page allowance, the monthly refresh budget ran out, or an include/exclude rule filtered them out.

Fixes:

1. Confirm the page opens publicly in a private browser window.
2. Use sitemap mode for broad coverage or manual URLs for a curated set.
3. Submit the canonical URL rather than a tracking URL, redirect URL, or logged-in URL.
4. Re-scrape after publishing content changes and after the refresh cooldown: at least seven days since the latest job was created on Free, or 24 hours on paid plans, even if that job failed.
5. Compare the job's saved/selected counts and the Content list with your intended URLs. Completed can include skipped/failed URLs; Completed with warnings specifically flags partially retained page text, not all crawl failures. The UI does not provide a complete per-URL failure list.

ChattyBox does not currently read or enforce robots.txt. It follows safe HTTP redirects, so a redirect alone is not a failure. Do not remove access protections or put private content on a public URL to make it crawlable.

If a URL was removed from your site or source selection, its stored page may still be used. Delete it from Content as well as excluding it from future discovery. Rebuild Index uses stored text, not a fresh network fetch, and has its own plan cooldown plus usage against the monthly refresh budget.

Settings Will Not Save

Save General Settings with Save Changes and Scraping Configuration with Save Config before the first scrape. Saving one form does not save the other. A saved Website URL is required by the dashboard even when you enter Manual URLs.

If the project is Config locked, configuration must be deployed through the CLI workflow. The lock is irreversible; Persona saves, scrape configuration, Scrape Now, content deletion, and index rebuilds are rejected even if a control is still visible. Only the branding preference remains dashboard-editable within hosted-widget configuration, subject to the plan. Public widget keys and deployment tokens are separate credentials.

If a project is missing or access is denied, confirm you signed in as its owner. A widget key, deployment token, or organization membership does not grant dashboard ownership permissions. Locked Analytics and Content Gaps tabs require Pro or Business; Logs is available on all plans.

Still Stuck

Collect these details before contacting support:

• The public page URL where the widget should appear.
• A screenshot or copy of any browser console error.
• Whether the page uses plain HTML, Next.js, Docusaurus, WordPress, a CMS, or Google Tag Manager.
• Whether the snippet includes data-api-key and data-api-url.
• One test question that should work and the source page that answers it.