For crawling specifically there are dedicated pages: Crawl Failed and Crawl Behind Cloudflare. This page covers the widget, answer quality, language, channels and caching.
Widget doesn't appear
If the chat widget doesn't show up on your site, work through these points in order. In most cases it comes down to a missing snippet, an unverified domain or the browser cache.
1
Is the snippet actually embedded?
Open the page, press
Ctrl/Cmd + U (view source) and search for widget.js. The snippet must look exactly like this — with your real Install ID in the data-alpheris-key attribute:HTML
<!-- Alpheris Chat Widget -->
<script src="https://alpheris.com/widget.js" data-alpheris-key="INSTALL_ID" crossorigin="anonymous" async></script>
<!-- End Alpheris Chat Widget -->2
Is the script loading? (Network tab)
Open DevTools (F12) → Network tab → reload the page → filter for
widget.js. You should get a 200 response. A 404 means a wrong snippet, a 403 points to a domain or plan block.3
Is the domain verified?
Alpheris binds every Install ID to the verified domain and, in the active Strict Domain mode (default), checks the origin of the embed. If the widget runs on a domain other than the verified one (e.g. staging, a new subdomain), it is blocked. For verified domains and
www. handling, see Domains.4
Content Security Policy (CSP)
If your site has a strict CSP,
alpheris.com must be allowed in script-src (and, for the connection, in connect-src), otherwise the browser blocks the script. The console will then show a CSP error message.5
Rule out ad blockers & cache
uBlock, AdBlock Plus & co. sometimes block chat widgets. Test in a private window without extensions and clear the cache (see the section Cache & changes not showing up).
Shopify and WordPress installations verify the domain automatically and set the snippet themselves. If the widget still doesn't appear, check in the Console under Dashboard → Integration whether the integration is still connected.
Answers are wrong, generic or off-topic
Alpheris answers grounded — that is, based on your knowledge base (crawled website, uploaded files, and for Shopify the synced products). If answers sound wrong or evasive, the knowledge base is almost always incomplete or outdated.
1. Check the knowledge base
- Is the domain crawled? Console → Data Sources & Knowledge Base: Is your website listed as a source and did the crawl finish successfully? If it failed, the Crawl Failed page helps.
- Missing content? If information only exists in PDFs, price lists or internal documents, upload it as a file. Allowed formats include
.pdf,.txt,.md,.csv,.docx,.xlsxas well as images — not allowed are.htmland.svg. Details under Data Sources. - Changed the site? The bot does not pick up website changes automatically in real time. After bigger updates, trigger "Re-crawl" in the Console so the knowledge base is refreshed.
2. Answer style & AI Agent
- Sharpen tone & instructions: Under AI Agent you can define tone and behavior. The more specific the instructions, the more precise the answers.
- Mind the channel tone: Each channel has its own profile — email formal/medium-length, web chat balanced/medium-length, WhatsApp & Instagram friendly/short. A short WhatsApp reply is therefore intended, not a bug.
If the AI finds no solid basis in the knowledge base, it deliberately answers cautiously instead of guessing. This is intended — it protects against made-up statements. The right lever is then almost always more/more up-to-date content, not a different answer style.
Wrong language in the answers
Alpheris automatically detects the language of the customer's message and answers in that language. If something is off, the following usually helps:
- Very short or mixed messages ("ok", "thanks", single product names) provide little signal — here the fallback language kicks in. A complete question reliably leads to the right language.
- If the bot consistently answers in the wrong language, check whether your knowledge base content is predominantly in another language — if there are only English sources on a topic, the answer can tip that way.
- More on language logic and the fallback language under Multilingual.
Channel issues (email, WhatsApp, Instagram)
In addition to the web chat widget, Alpheris can also handle email and messaging channels in the Inbox. Typical pitfalls:
| Symptom | Cause | Solution |
|---|---|---|
| Channel doesn't send automatic replies | Maturity still in observation mode | New intents start in Shadow → Copilot → Autopilot. Suggestions are only sent automatically after enough accepted answers. Until then you can release them manually in the Inbox. |
| Complaints are never answered automatically | Deliberate safety rule | The "Complaint" intent cluster is permanently excluded from Autopilot and always lands with you as a suggestion. |
| WhatsApp/Instagram not connected | OAuth expired or cancelled | Re-authorize the integration in the Console. The connection runs via Meta OAuth with webhook verification. |
| Emails don't arrive | Mailbox connection dropped | Re-authorize the Outlook/Microsoft connection; for your own SMTP/IMAP, check the credentials. |
| Voice output/input missing | Plan restriction | Voice is only available from the Business plan. See Plans & Billing. |
If you get a
402 plan required when accessing the Inbox API, the right plan is missing: the external API is only available in Business and Enterprise. More on this in the API Reference.Cache & changes not showing up
You changed something (snippet, design, content), but nothing changes? A cache layer is almost always to blame. Work your way from the outside in.
1
Clear the browser cache
A hard reload reloads the widget script:
Ctrl + F5 (Windows) or Cmd + Shift + R (Mac). As a cross-check, open a private window.2
The shop's CDN / hosting cache
Platforms like Shopify, or caching plugins/CDNs (e.g. Cloudflare in front of your site), cache the HTML. Clear the cache there so the updated snippet is served.
3
Content changes: trigger a crawl
Changed website content only lands in the knowledge base after a re-crawl. Click "Re-crawl" in the Console and wait for it to finish.
4
Check the design preview
Design changes can be verified via the live preview in the editor before you go looking for them on the real site. Details under Design.
Going further
If none of this helps, check the relevant detail pages or reach out to support:
Crawl Failed
When your website isn't being read in
Knowledge Base
Sources, uploads & re-crawling
Domains
Verification & Strict Domain mode
FAQ
Quick answers to common questions
If it stays stuck, the team can help: via the Console or by email to [email protected]. Describe the domain, the affected channel and what you've already checked — that speeds up the solution considerably.