Troubleshooting

Verify the widget script, CID, network requests, configuration, and JavaScript API

Use the browser’s developer tools to check the actual installation before changing application code.

The chat bubble does not appear

1. Confirm the page contains exactly one installation tag and that cid is not empty:

   <script src="https://cdn.bubblo.ai/widget.js" cid="YOUR_CHANNEL_ID"></script>

2. In Network, confirm https://cdn.bubblo.ai/widget.js loads successfully.

3. In Console, check that the host API exists:

   typeof window.Bubblo?.open === "function"

4. In Elements, look for #bubblo-widget-host. The script creates this element after it executes.

5. Compare the cid value with the Widget CID shown under the install code in Integrations → Widget for the same organization.

6. In Network, inspect GET https://chat.bubblo.ai/v1/chat/{cid}/config. A usable configuration response has an HTTP success status and a JSON code of 200.

If widget.js or the chat request is blocked, inspect Console for a Content Security Policy error naming cdn.bubblo.ai or chat.bubblo.ai.

The panel opens but messages do not work

Run window.Bubblo.open() in Console, then inspect Network:

• The EventSource request to /v1/chat/{cid}/visitor/event should remain open.
• Sending a message should create a POST request to /v1/chat/{cid}/visitor/message with a successful HTTP status.

An error on either request identifies the failing connection. Check the response and any matching browser console error.

Appearance changes look stale

The installed widget fetches its configuration when it mounts, and the configuration response may be cached for up to 60 seconds.

1. Confirm you selected Save changes at the bottom of the appearance form in Integrations → Widget.
2. Wait up to 60 seconds.
3. Reload the installed page so the widget mounts and fetches the configuration again.

Use Customize the widget to confirm which settings are currently supported.

window.Bubblo is undefined

window.Bubblo is created when widget.js executes. Check the CDN request first. Calls made after the script executes but before the visual widget mounts are supported by the pre-mount queue.

Identity metadata is missing

After calling identify(), inspect the browser value:

JSON.parse(localStorage.getItem("bubblo_visitor_identity"))

Then send a new visitor message and inspect its /visitor/message request payload. Identity fields are attached to subsequent messages; they are not added retroactively to earlier messages.