Troubleshooting

The assistant loads the same way on every platform, so almost every install problem is one of a few things. Work down this list — issues 1 and 3 cover the large majority.

Test on a preview page first (recommended)

The fastest way to avoid every install problem below is to confirm the assistant renders and answers before you put it on your production site — load the snippet on a staging or platform preview page you control:

1. In your assistant’s settings, allowlist your platform’s build/preview domain (*.webflow.io, *.myshopify.com, etc. — see the table below), your own staging hostname, or localhost.
2. Add the snippet to that page and open it. Ask a few sample questions, confirm the answers are grounded in your content, and check that the launcher renders.
3. When it looks right, add the snippet to your production hostname (allowlist that too).

The launcher doesn’t appear

1. Your domain isn’t allowlisted (most common)

The loader fetches your assistant’s config before it renders anything. If the page’s hostname isn’t in your Install domains list, the request is rejected (403) and no launcher appears.

Check the dashboard first — no console needed. Your assistant’s Install step has an Install status card listing every hostname the snippet has loaded from, on any platform. A blocked hostname appears there with a one-click Allow button — that click adds the exact host shown (wildcard patterns like *.myshopify.com from the table below remain a manual add under Install domains).

The loader also prints an actionable error to the browser console naming the exact hostname that was rejected — open the developer console (F12) on the page and look for the Olotalk message if you prefer debugging in place.

Fix: in the dashboard, open your assistant’s settings and add the exact hostname where the snippet runs to its Install domains (add www. too if you use it). Wildcards like *.example.com are supported.

Add your platform’s build/preview domain as well — this is the step people miss:

2. The platform stripped the script’s attributes

Some CMSs and editors sanitize markup and drop unknown attributes. View your page source: if the <script> tag is there but data-olotalk-assistant-id is gone, this is your problem (common with WordPress wp_enqueue_script, WYSIWYG editors, and over-eager security plugins).

Fix: use the attribute-free configuration form instead — set window.OlotalkConfig first, then load the bare loader:

<script>
  window.OlotalkConfig = { assistantId: 'YOUR_ASSISTANT_ID' };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  async
></script>

Or inject the snippet through a method that preserves raw HTML — a headers-and-footers plugin, Drupal’s Full HTML format, or a code-view editor.

3. Your snippet is trapped in an iframe

If you see a small empty box sitting inline in your content — or the chat only shows up inside one section — your snippet went into a per-section “Embed HTML” element. Those render inside an iframe, and a floating launcher can’t escape it.

Fix: move the snippet to the platform’s site-wide custom code / footer feature instead. This affects Wix (use Custom Code, not the Embed element), Squarespace (use Code Injection, not a Code Block), and Carrd (use Embed Type: Code, not IFRAME).

4. You’re looking at the editor, not the published site

Webflow, Framer, Wix, Squarespace, Carrd, and BigCommerce run custom code only on the published site — not in the editor or preview. Publish, then open the live URL.

The launcher appears but won’t answer

• You get a fallback like “I don’t have that information yet.” Your content isn’t ingested. Add a URL under your assistant’s Source step and ingest it — see the Quick start.
• Nothing happens when you send a message, or you see console errors. Check your Content Security Policy (below) and the config request (debug steps below).
• The composer is greyed out and nothing sends. You have a consent banner enabled on your assistant’s Policy step. That banner is a gate, not a notice: until the visitor acknowledges it, no session is created and no message is sent. That is deliberate — a consent notice that let the conversation proceed anyway would claim consent it never collected. Turn it off under Policy → Consent tracking, or leave it on and expect the first click to be the acknowledgement.
• It answers in the wrong language. The language is picked per visitor and bounded by your assistant’s supported set — see Multilingual for the exact priority chain and how to pin one.

Content Security Policy (CSP)

If your site sets a strict CSP, the browser may block the loader or its API calls. Allow Olotalk’s hosts:

script-src 'self' https://cdn.jsdelivr.net;
style-src 'self' https://cdn.jsdelivr.net;
connect-src 'self' https://api.olotalk.com https://cdn.jsdelivr.net;

Adjust the hosts if you self-host the assistant bundle. See the Embed reference → Security for the full policy.

Debug it in under a minute

1. Open your browser DevTools → Network tab and reload the page.
2. Find the request to …/public/v1/assistants/<your-assistant-id>/config:
   • 403 → your domain isn’t allowlisted (issue 1). In sandbox testing, it can also mean a missing or expired preview token.
   • 429 → you’re being rate-limited; wait a minute and retry.
   • 404 on loader.iife.js → the snippet’s src URL is wrong.
   • no request at all → the script never ran — it was stripped, blocked by CSP, or the site isn’t published (issues 2–4).
3. Check the Console for any Olotalk warnings.
4. Grab the x-request-id response header — include it when you contact support; it correlates your request to our server logs.

Privacy: what the embed stores and sends

The complete inventory, for whoever maintains your privacy policy and consent banner:

• In the visitor’s browser: two localStorage keys — olotalk_visitor_id (an anonymous visitor identifier) and olotalk:lang:<assistantId> (a language choice the visitor accepted). No advertising cookies, no third-party pixels.
• Over the network: the loader sends a page-view beacon (page URL, referrer, UTM tags) when it loads, and conversations go to Olotalk’s API to be answered. Nothing is written into your own site’s database.

Whether any of that must appear in your cookie banner is a legal question that depends on your jurisdiction — these docs can hand you the inventory, not the answer. See Olotalk’s Privacy Policy, and if you load the snippet through a tag manager, the Google Tag Manager guide covers firing it behind consent.

Removing, pausing or moving it

• Remove: delete the snippet (or deactivate the plugin). Nothing else lives on your site; the two localStorage keys above are inert leftovers without the script.
• Pause: take the assistant offline in the dashboard — the snippet can stay in place, and the assistant simply stops rendering (the loader says why in the browser console).
• Move to a new domain: add the new domain under Install domains, paste the snippet there, and remove the old one when ready. The assistant, its content and its conversation history are untouched — the Install status card shows the new domain on its first load.
• Archived or deleted assistant: an embed left behind renders nothing and logs “no longer available — remove this embed snippet.”

Still stuck?

Contact support with your assistant ID, the platform you’re installing on, and the x-request-id from the failed request. Before you do, re-check issues 1 (domain allowlist) and 3 (iframe) — that’s where most installs go wrong.