JavaScript API

Open, close, and identify visitors from your host page

After the widget script is installed, it exposes window.Bubblo on the host page.

Methods

open()

Open the chat panel. The widget establishes its chat connection the first time it is opened.

window.Bubblo.open()

close()

Hide the chat panel. Closing it does not erase the visitor ID, identity metadata, or conversation.

window.Bubblo.close()

identify(payload)

Attach optional application-provided identity fields to subsequent visitor messages:

window.Bubblo.identify({
  userId: "u_123",
  email: "ada@acme.com",
  name: "Ada",
})

All three fields are optional. userId is sent as user_id in message metadata. The identity is stored in the visitor’s browser so it remains available after a reload.

Calling identify() with no payload clears the previously stored identity fields for subsequent messages:

window.Bubblo.identify()

Calls made before the widget mounts

The script installs window.Bubblo before the visual widget finishes mounting. Calls made during that interval are queued and replayed in order when the widget is ready. This makes the following safe immediately after the installation tag:

<script src="https://cdn.bubblo.ai/widget.js" cid="YOUR_CHANNEL_ID"></script>
<script>
  window.Bubblo.identify({ userId: "u_123" })
  window.Bubblo.open()
</script>

This queue starts only after widget.js has executed. If window.Bubblo is undefined, the script has not loaded or has been blocked.

Metadata and privacy

The widget creates a random visitor ID and stores it in the visitor’s localStorage so the same browser can resume its conversation after a reload. Identity fields set with identify() are stored separately in the same browser.

Each visitor message automatically includes the following page context as metadata:

• Full page URL from location.href
• Page title
• Referrer
• Browser language

Fields supplied through identify()—user_id, email, and name—are added to the same metadata and persisted with the visitor message.

Review your URLs and privacy notice before deployment. A full page URL can contain query parameters, and identity fields can contain personal data. Do not put passwords, session tokens, API keys, or other secrets in URLs or in identify().

identify() is client-side metadata, not authentication. A visitor can inspect or alter values sent by their browser. Never use these fields to authorize an action, grant access, or decide whether sensitive information may be returned.