Glozr docs
/

Embed the widget

Embed

The Glozr widget is a lightweight chat surface delivered through a single <script> tag. The bundle is roughly 50 KB gzipped, mounts inside a Shadow DOM, and loads asynchronously so it never blocks page rendering.

The snippet

Paste this just before the closing </body> tag of any page where you want the widget to appear.

<script
    src="https://app.glozr.com/widget/widget.js?v=ab12cd34"
    data-agent-id="01HXY..."
    async></script>

Each agent's Settings page exposes the exact snippet with your data-agent-id already baked in — copy it from there rather than typing it by hand.

What each attribute does

  • src — points to /widget/widget.js on your Glozr deployment. The ?v= hash rotates on every rebuild so browsers and CDNs never serve a stale bundle.
  • data-agent-id — the ULID of the published agent you want to render.
  • async — guarantees the script never blocks parsing or paint.

Boot sequence

When the page loads, the widget runtime:

  1. Appends a host <div> at the end of <body> and attaches a Shadow DOM to it.
  2. Renders the launcher button inside the shadow root so your page CSS never bleeds in.
  3. Calls POST /v1/widget/init to fetch the agent config, a signed JWT, and the visitor's recent conversation history.
  4. Wires up trigger listeners based on the agent's behavior rules.
  5. Persists an anon_id in localStorage so returning visitors resume their thread.

Theming and customization

Theme is agent-driven — position, primary color, accent color, corner radius, and launcher label are all configured from /app/agents/{id}/customize. Per-page styling overrides are intentionally not supported; if you need a different look on two surfaces, publish two agents and use two snippets.

Single-page apps

The widget survives client-side navigation as long as the script tag stays in the DOM. If your framework remounts <body> on every route change, the runtime will reinitialize and pick the conversation back up from recent history.

Caching strategy

Because the ?v= query string is a content hash, the widget asset can be served with year-long Cache-Control headers. Each rebuild produces a new hash, so visitors automatically pull the fresh bundle the next time they load a page that hosts the widget.

Note. The widget script is public on purpose — the trust boundary that keeps a third party from embedding your agent on their own site is allowed origins, not the snippet itself.