Configuration

Configure WidgetClient by passing a WidgetConfig object to the constructor. All options except widgetKey are optional.

WidgetConfig

Option	Type	Required	Default	Description
widgetKey	string	Yes	—	Your widget installation key
baseUrl	string	No	https://api.univerx.ai	API base URL
container	string | HTMLElement	No	—	Mount the widget inside a specific DOM element or CSS selector
theme	WidgetTheme	No	—	Visual customisation
cursor	CursorConfig	No	—	Agent cursor overlay settings
onReady	() => void	No	—	Called when the SDK is ready
onError	(error: Error) => void	No	—	Called on unhandled errors
onAgentAssigned	(agent: Agent) => void	No	—	Called when an agent accepts the session
onCallStarted	() => void	No	—	Called when the video call begins
onCallEnded	() => void	No	—	Called when the video call ends
onCobrowseStarted	() => void	No	—	Called when cobrowsing begins
onCobrowseEnded	() => void	No	—	Called when cobrowsing ends
onCobrowseConsentRequired	(handlers: CobrowsingConsentHandlers) => void	No	—	Called when the agent requests cobrowsing consent

Theme

Control the visual appearance of the widget with WidgetTheme:

const widget = new WidgetClient({
  widgetKey: "your-widget-key",
  theme: {
    primaryColor: "#6366f1",
    position: "bottom-right",
    borderRadius: "12px",
    fontFamily: "Inter, sans-serif",
  },
});

Option	Type	Description
primaryColor	string	Brand color for buttons and accents (any CSS color value)
position	"bottom-right" | "bottom-left" | "top-right" | "top-left"	Widget position on screen. Defaults to bottom-right
borderRadius	string	Corner radius of the widget panel (any CSS value, e.g. "8px")
fontFamily	string	Font used inside the widget (any CSS font stack)

Cursor options

Control the agent cursor overlay with CursorConfig:

const widget = new WidgetClient({
  widgetKey: "your-widget-key",
  cursor: {
    enabled: true,
    autoHideDelay: 2000,
    showLabel: true,
    clickAnimation: true,
  },
});

Option	Type	Default	Description
enabled	boolean	true	Show or hide the agent cursor overlay
autoHideDelay	number	2000	Milliseconds before the cursor fades after the agent stops moving
showLabel	boolean	true	Show the agent’s name next to the cursor
clickAnimation	boolean	true	Animate a ripple when the agent clicks

Custom container

By default the widget renders a floating button in the corner defined by theme.position. To mount it inside your own element instead, pass a CSS selector or a DOM reference:

const widget = new WidgetClient({
  widgetKey: "your-widget-key",
  container: "#support-widget",
  // or: container: document.getElementById("support-widget"),
});

The element must exist in the DOM before widget.init() is called.

Domain allowlisting

Each widget key is locked to a set of trusted domains. Requests from other origins are rejected with a 403 error.

To add a domain:

1. Open your Univerx dashboard and go to Settings → Widgets.
2. Select your widget and open the Domains tab.
3. Enter the full origin of your site, including protocol (e.g. https://example.com).
4. Verify ownership using the DNS TXT record or HTML meta tag provided.

Caution

Domain verification is required before the widget can initialise on that domain. Unverified domains will cause init() to fail with a 403 error.

API reference: WidgetClient Full method and event reference with TypeScript signatures.