Reference

Embed Types

Five ways to embed your agent. Pick the one that fits your product.

	Bubble	Sidebar	Popup	Inline	Headless
Self-contained UI	✅	✅	✅	✅	—
Overlays content	No	Optional	Yes	No	N/A
Always visible	No	No	No	Yes	N/A
Programmatic control	Partial	Partial	✅	—	✅
Custom HTML/CSS	Themes	Themes	Themes	Themes	Full

Bubble

Default

A floating action button fixed to a corner of the screen. Opens a chat panel on click. The easiest way to add Widgent to any page.

Best for: General SaaS apps, support flows, onboarding helpers.

js / html

<script src="https://cdn.widgent.app/index.global.js"
  data-product-id="YOUR_PRODUCT_ID"
  data-embed="bubble"
  async>
</script>

Option	Value
`position`	"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"
`offsetX`	number (px from edge)
`offsetY`	number (px from edge)
`size`	"sm" \| "md" \| "lg"

Sidebar

A slide-in panel from the right (or left) edge. Doesn't obscure the full page — the user can still see and interact with content.

Best for: Dashboards, data-heavy apps, anywhere the user needs to multitask.

js / html

window.widgent.init({
  productId: 'YOUR_PRODUCT_ID',
  serviceKey: 'YOUR_SERVICE_KEY',
  type: 'sidebar',
  side: 'right',   // 'right' | 'left'
  width: 380,      // px or '%'
  push: true,      // shrink the app instead of overlay
});

Option	Value
`side`	"right" \| "left"
`width`	number (px) or string ("30%")
`push`	boolean — shrink app content instead of overlaying

Popup

A centered modal overlay. Full attention. Good for onboarding flows, or when the agent needs the user's full focus.

Best for: Onboarding wizards, support escalation, focused task flows.

js / html

window.widgent.init({ productId: 'YOUR_PRODUCT_ID', serviceKey: 'YOUR_SERVICE_KEY', type: 'popup' });

// Trigger programmatically
window.widgent('open');
window.widgent('close');
window.widgent('toggle');

Option	Value
`maxWidth`	number (px)
`backdropBlur`	boolean
`backdropColor`	CSS color string

Inline

The chat renders directly into a container element you place in your HTML. Always visible — no button to click.

Best for: Dedicated help/support pages, AI-powered search, product guides.

js / html

<!-- Place this in your HTML where you want the widget -->
<div id="widgent-inline" style="height: 520px;"></div>

<script src="https://cdn.widgent.app/index.global.js"
  data-product-id="YOUR_PRODUCT_ID"
  data-embed="inline"
  data-target="#widgent-inline"
  async>
</script>

Option	Value
`target`	CSS selector for the container element
`height`	Inherit from container (set via CSS)

Headless

Advanced

No UI at all. Widgent provides the connection, session management, and tool routing — you build your own interface completely.

Best for: Fully custom chat UIs, deeply integrated agent experiences.

js / html

window.widgent.init({ productId: 'YOUR_PRODUCT_ID', serviceKey: 'YOUR_SERVICE_KEY', type: 'headless' });

// Send a message with streaming callbacks
window.widgent('send', {
  message: 'Show my recent orders',
  onChunk:    (text)            => appendToUI(text),
  onToolCall: (name, params)    => handleTool(name, params),
  onDone:     (fullText)        => finalizeMessage(fullText),
  onError:    (err)             => showError(err),
});

Option	Value
`—`	All UI is your responsibility
`Events`	widgent:ready, widgent:message, widgent:tool-call