Troubleshooting
The launcher is fine, so why is there nothing above it
The launcher and the panel are two different things loaded at two different times. The launcher ships with the loader and appears on page load; the panel is a separate document, fetched the first time somebody clicks. Almost every problem in this shape lives in that gap, which is good news, because it narrows the search enormously.
The symptom
The launcher renders, responds to hover and click, and nothing opens above it.
What it usually is
In rough order of how often each one turns out to be the answer. Work down rather than across: each carries a way to tell whether it is yours before you change anything.
- 1
The panel document is blocked by a frame policy
- Why
- The panel is an iframe, and a page policy that does not permit the frame source blocks it at the moment of the first click rather than at page load.
- How to confirm it is this one
- The console shows a violation naming frame-src or child-src at the moment you click, and not before.
- Fix
- Add the loader origin to frame-src. This is by far the most common cause and it is the one that hides for longest, because everything looks correct until the first person clicks.
- 2
An extension or filter list is removing the frame
- Why
- Privacy extensions block third-party frames as a category, and a chat panel in a frame from another origin is exactly the shape they target.
- How to confirm it is this one
- It opens in a private window with extensions disabled and does not open in the normal profile.
- Fix
- Nothing to fix on your side, and nothing you should try to work around. A visitor who has chosen to block third-party frames has chosen it, and the launcher failing quietly is the correct outcome.
- 3
The panel loaded but never reported itself ready
- Why
- The panel tells the loader it is ready by posting a message, and the loader holds everything it wants to send until that arrives. A panel that loaded but failed to run its script never sends it.
- How to confirm it is this one
- The frame element is present in the DOM after the click, and the panel area is blank rather than absent. In the network tab the panel document returns 200 but its script does not.
- Fix
- Check whether anything is filtering scripts on the panel origin specifically. This is rare and usually points at a network-level filter rather than at your page.
- 4
The panel is opening off screen
- Why
- The panel is positioned relative to the launcher using the offsets in the appearance settings, and its height is capped against the viewport. Extreme offsets can put it outside the visible area.
- How to confirm it is this one
- Scroll the page while the panel is open, or reduce the offsets to their defaults temporarily and click again.
- Fix
- Bring the offsets back to something sane. The panel already caps its own height against the viewport, so this only happens with deliberately large values.
If none of those fit
On a narrow screen the panel takes the whole viewport and hides the launcher while it is open, which is the intended behaviour rather than a fault. If you are testing on a phone and think nothing opened, check whether the whole screen changed.
Questions
- Why is the panel a separate document at all?
- Two reasons that both matter. Nothing in your page can read the conversation, because it is in another origin, and nothing in your page can restyle it or be restyled by it. The cost is that it is governed by a frame policy, which is the failure above.
- Why is it not loaded up front?
- Because most visitors never open it. Loading the whole conversation interface on every page view for the few who click would be a page speed cost paid by everybody for the benefit of a minority.
- Does the panel work with a sandbox attribute on my own frames?
- Your sandbox settings apply to frames you create. The panel is created by the loader with its own sandbox settings, which permit scripts, same-origin storage and form input, and nothing else.
Keep reading
- The chat widget is not appearing on my siteSix reasons the launcher does not render, each with the console line or network response that tells you which one you have hit.
- This site is not on the allowlist for this assistantThe allowlist is an exact string match with no wildcards, so www, http and a port each count as a different site. Here is how to read the message.
- A Content Security Policy is blocking the chat widgetFour directives govern the widget from your page: script, style, frame and connect. Here is what each one blocks and how the failure looks.
- Install guides by platformWhere the tag goes, and what overwrites it, on each hosting platform.
- Everything that goes wrongSymptom, cause, how to confirm which one, and the fix.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.