Widget Embed

The Zimmer widget loads your agent as a floating chat button on any webpage. Users click it to open a full conversation experience without leaving your site. The widget is a lightweight JavaScript snippet -- no framework dependencies, no npm package required.

Setup

Open your agent → Settings → Deploy
Copy the Widget Embed Code
Paste it before the closing </body> tag on your website

<script
  src="https://hub.zimmer.app/widget/v1/widget.js"
  data-agent="your-agent-id"
></script>

For site-wide placement, add it to your layout template or global script field in your website builder (Webflow, WordPress, Shopify, and most CMS platforms support this).

Using a starter kit instead of an agent ID

You can also load a widget using a starter kit slug instead of an agent ID:

<script
  src="https://hub.zimmer.app/widget/v1/widget.js"
  data-kit="internal-knowledge-agent"
></script>

One of data-agent or data-kit is required.

Configuration attributes

All configuration is done through data-* attributes on the script tag. No JavaScript API is needed.

Attribute	Required	Default	Description
`data-agent`	One of agent/kit	—	The agent ID to load
`data-kit`	One of agent/kit	—	A starter kit slug (e.g., `internal-knowledge-agent`)
`data-color`	No	`#7C3AED`	Primary brand color for the floating button and UI accents
`data-position`	No	`bottom-right`	Position of the floating button: `bottom-right` or `bottom-left`
`data-greeting`	No	—	An initial greeting message displayed when the widget opens
`data-auto-open`	No	`false`	Set to `"true"` to automatically open the chat on page load
`data-delay`	No	`0`	Delay in milliseconds before the floating button appears
`data-product-id`	No	—	Explicit product ID for e-commerce context
`data-category`	No	—	Explicit category for e-commerce context

Example with all attributes

<script
  src="https://hub.zimmer.app/widget/v1/widget.js"
  data-agent="clx1234abcdef"
  data-color="#FF6B00"
  data-position="bottom-left"
  data-greeting="Hi! Need help finding the right size?"
  data-auto-open="true"
  data-delay="3000"
  data-product-id="SKU-12345"
  data-category="shoes"
></script>

Behavior

A floating action button (FAB) appears at the configured position after the optional delay.
Clicking the FAB opens the agent in an iframe overlay.
Closing the overlay preserves the conversation -- users can reopen and continue where they left off.
A persistent visitor ID is stored in the browser's localStorage (zimmer_visitor_<agentId>), so returning visitors resume their session.

E-commerce product detection

The widget automatically detects product and category context from the host page URL when data-product-id and data-category are not explicitly set.

Product detection patterns

The widget looks for product identifiers in URL paths matching common e-commerce patterns:

/products/<slug> or /product/<slug>
/p/<id>
/item/<id>
/dp/<id> (Amazon-style)

It also checks URL query parameters: ?product_id= or ?pid=.

Category detection patterns

/collections/<slug> or /collection/<slug>
/category/<slug> or /categories/<slug>
/c/<slug>

It also checks URL query parameters: ?category= or ?cat=.

When detected, product and category context is passed to the agent, allowing the journey to reference product-specific information in conversation nodes.

UTM and metadata capture

The widget automatically captures and forwards metadata about the visitor's session:

UTM parameters -- utm_source, utm_medium, utm_campaign, utm_term, utm_content from the host page URL
Referrer -- the document.referrer value
Page URL -- the current host page URL
Viewport dimensions -- the browser window size

This data is available inside the agent's journey as visitor metadata and can be used in conditions, variable assignments, or passed to API calls.

Starting over

If Allow "Start Over" is enabled in agent settings, users can type "start over" or "reset" at any point to return to the beginning of the conversation journey. The welcome message and original quick reply buttons reappear.

A visual "Conversation restarted" divider appears in the chat. All previous messages remain visible -- only the journey position resets.

New conversation

If New Conversation Button is enabled in agent settings, a pencil icon appears in the widget header after a few message exchanges. Clicking it creates a completely new conversation with a fresh visitor session. The previous conversation is preserved in your Conversations dashboard.

Product card CTAs

When a product card CTA is clicked inside the widget, a postMessage is sent to the host page instead of navigating away. Listen for it on your page to handle product actions (add to cart, navigate, etc.):

window.addEventListener('message', (event) => {
  if (event.data?.type === 'zimmer:cta_click') {
    console.log(event.data.url);           // product URL
    console.log(event.data.productTitle);  // product name
    // Handle the click -- e.g., add to cart, navigate, or track
  }
});

Technical details

The widget is built as a single IIFE (Immediately Invoked Function Expression) JavaScript file with no external dependencies. It creates an iframe pointing to the Zimmer chat UI and manages the floating button, open/close state, and PostMessage bridge between the iframe and the host page.

Conversations are established via WebSocket (Socket.io) -- there is no REST endpoint for widget conversations.

Landing Pages Playground