The widget does not appear

1. Check the script tag is on the page. View the page source and search for widget.js. In Next.js or React, confirm <SvellyoWidget /> is rendered in the root layout, not inside a page that may be excluded.

2. Check the workspace id. It must start with ws_ and match Settings → Installation exactly.

3. Check excluded paths. If the current URL matches excludePaths, data-exclude or Settings → Widget → Hide on these pages, the widget is intentionally hidden.

4. Check the launcher setting. With the launcher set to Hidden, nothing shows until you call window.Svellyo("open").

5. Ad blockers. Some aggressive blockers stop chat widgets. Test in a private window without extensions.

6. Content Security Policy. If your site sets a CSP, allow https://cdn.svellyo.com for scripts and https://svellyo.com for connections. Realtime also needs wss://*.pusher.com.

"Chat is not available on this site"

The page's domain is not in Settings → General → Allowed origins. Add it exactly as the browser shows it, including the scheme, for example https://app.acme.com. Use https://*.acme.com for all subdomains, or * while testing. Changes apply within a minute.

Visitors see "We'll reply as soon as we're back" or the message form

Either nobody on the team is online and the AI is off, or you are outside business hours with auto-escalate when offline on, or the owner's plan is over its monthly chat limit. Check Settings → AI, Settings → Hours and the usage meter on the workspace home page.

The AI does not reply

• AI is disabled for the workspace under Settings → AI.

• The conversation is in human mode. Once a teammate replies, the AI stays out until you click Hand back to AI.

• Over the plan limit. The AI pauses at 100% of monthly chats. Upgrade or wait for the next month.

• Empty knowledge base. The agent will still reply, but with low confidence it hands off quickly. Add articles or a crawl and retry with the Test chat.

• Daily spend cap. As an abuse protection there is a daily AI spend cap per account. If you hit it, the AI resumes the next day; contact us to raise it.

The AI gives wrong answers

Find the answer's sources in the thread. If the wrong article was used, improve titles and split long articles so the right passage ranks higher. If the information is simply missing, add it, ideally as an AI only article with exact numbers. Tighten the persona instructions with "Only answer from the knowledge base" and raise the confidence threshold so it hands off instead of guessing.

Messages arrive late or only after a refresh

The inbox and widget poll every 15 seconds as a fallback, so you will always get messages, just not instantly. Instant delivery needs the realtime connection, which can be blocked by corporate proxies or a CSP that does not allow wss://*.pusher.com.

The knowledge base crawl found few pages or failed

• The crawler follows links on the same site only and respects robots.txt.

• Pages rendered entirely by JavaScript may come back empty; if your docs are static or server-rendered they work best.

• Page limits per source are 25 on Free, 200 on Pro and 1,000 on Scale. Split large sites into several sources by section.

• Re-run the crawl from Knowledge base → Sources after fixing the site, and set a refresh schedule.

Help center custom domain will not verify

Create a CNAME record from your subdomain (for example help) to the target shown in Knowledge base → Help center, then click Verify. DNS changes can take up to an hour. Do not proxy the record through a CDN with its own certificate; leave it as a plain CNAME. Custom domains need the Pro or Scale plan.

Identify is ignored

If Require verified identity is on, identify needs a valid hash. Confirm you are hashing the userId (or the email when there is no userId) with the workspace's current identity secret using HMAC-SHA256 as hex. Regenerating the secret invalidates old hashes.

The widget looks wrong on my site

The widget renders inside a Shadow DOM, so your CSS cannot leak in. If the launcher is covered, another element on your page has a higher z-index or a fixed footer in the same corner; move the launcher to the other side under Settings → Widget → Position. If the panel is cut off on mobile, check for a <meta name="viewport"> tag.

Still stuck?

Open the widget on svellyo.com and tell us the workspace id, the page URL and what you expected to happen. Screenshots help.