Troubleshooting

Symptom, cause, fix. Grouped by where the problem shows up.

On this page

The widget does not appear
Answers are wrong, thin, or missing
Crawl problems
Live chat is not available
Webhooks are not arriving
Billing and credits

The widget does not appear

Confirm the script is in the served HTML
View source (not the inspector, which shows the DOM after JavaScript has run) and search for oyechats-widget.js. If it is not there, your CMS or template did not publish the change.
Check it is inside <body>
A script in <head> can run before there is a body to attach to.
Check the bot key
A typo, a truncated paste, or a placeholder still reading YOUR_BOT_KEY all produce silence. Copy it fresh from the dashboard.
Check the domain allowlist
If Advanced → Allowed domains does not include the exact hostname you are on, requests are rejected. www and non-www are different hostnames.
Look at the console
Widget messages are prefixed [OyeChats]. Run OyeChats.diagnose() for version, mount state and resolved configuration.
Rule out blockers
Some content blockers and strict corporate proxies block third-party chat widgets. Test in a clean profile.

A consent gate will hold it back deliberately. If window.OYECHATS_ASYNC_INIT = true is set, nothing mounts until OyeChats.init() is called. Confirm your consent manager actually calls it.

Answers are wrong, thin, or missing

Symptom	Most likely cause	Fix
"I don't have that information"	The topic is not in the knowledge base, or the page holding it was not indexed.	Check the indexed page list. Crawl the missing page or upload the document.
Answers quote out-of-date facts	Answers come from the index, not the live web.	Re-crawl, or turn on automatic weekly re-crawl.
An uploaded PDF taught it nothing	The PDF is a scan with no text layer.	Run OCR first, or paste the text into a `.txt` or `.md` file.
It refuses on-topic questions	The services list is set and the question falls outside it.	Widen or clear the services list under Advanced.
Answers are vague across the board	Many near-duplicate pages are competing for retrieval.	Remove duplicate and thin pages; keep one thorough page per topic.
Tone is off	Brand tone or system prompt.	Set a tone preset and tighten the system prompt.

Start with Unanswered questions. Analytics → Unanswered questions is a ranked list of what your knowledge base is missing. It beats guessing.

Crawl problems

It found almost no pages: Discovery tries your sitemap first, then a same-domain link scan. Both come up short on a client-rendered site whose links only exist after JavaScript runs, and robots.txt Disallow rules are honoured, so check those first. Publishing a sitemap is the most reliable fix. It also reaches orphaned pages a link scan cannot. Failing that, point the crawler at a section root that links out widely rather than a sparse landing page, or upload the content directly.
Pages indexed but empty: Content that renders only after user interaction, or is behind a login, has nothing to extract. Only what a public visitor sees is indexed.
It stopped short of the whole site: A plan cap on pages, crawl depth, or JavaScript-rendered pages. Workspace → Usage shows which cap you met.
It failed part-way: Pages already indexed are kept. Re-run the crawl; it skips unchanged pages.

Live chat is not available

Work down the seven availability states in order. The first match wins, and the answer is almost always one of the first four:

Does your plan include live chat, and is the chatbot's toggle on?
Does the workspace have at least one operator?
Is it inside business hours, in the timezone you configured?
Is at least one operator actually online and accepting chats?
Is the queue full, or is every online operator at their concurrency limit?

The Support inbox shows the current state as a pill, so you can read the answer instead of deducing it.

Webhooks are not arriving

Read the delivery log
Every attempt is recorded with its status code and response body. It usually names the problem outright.
Check you are subscribed to the right event
An endpoint subscribed only to lead_captured never receives tier_transition.
Check reachability
The URL must be HTTPS on a publicly resolvable host. Private, internal and loopback addresses are rejected at registration.
Check your response
Only 2xx counts as delivered, and you have 10 seconds. Return quickly and do the work afterwards.
Check your signature verification
A silent 401 from your own handler is the most common cause of "webhooks not working". Hash the raw body bytes, before any parse or re-serialise.

Once your endpoint is healthy, failed deliveries can be replayed from the dashboard. Full detail in Webhooks.

Billing and credits

Credits drained faster than expected: Check Workspace → Usage by action. A large crawl at 5 credits per page dwarfs conversation cost, and a re-crawl started manually is not the same as the free automatic one.
A feature is greyed out: It is not on your plan. The API returns feature_not_available with the feature name for the same reason.
Payment failed: You keep full access during the grace window. Update the payment method from Workspace → Billing; recovering the payment restores everything without re-subscribing.
GSTIN missing from an invoice: It was added after the invoice was issued. Add billing details before your first charge; already-issued invoices are not reissued.

Something here wrong or missing? Tell us and name this page. We will fix it.