WidgetClient API reference

WidgetClient is the main class exported by @univerx/client-sdk. It manages the full lifecycle of a visitor session: authentication, queue, video call, and cobrowsing.

Constructor

new WidgetClient(config: WidgetConfig)

Throws if called outside a browser environment or if widgetKey is not provided. See Configuration for the full WidgetConfig reference.

Methods

`init()`

widget.init(): Promise<void>

Authenticates with the Univerx API, sets up realtime channels, and starts cursor tracking. Must be called before any other method. Emits ready on success and sets state to error on failure.

Throws if called more than once on the same instance.

`submitForm()`

widget.submitForm(formData: Record<string, unknown>): Promise<void>

Submits pre-call form data (e.g. visitor name, email, issue type) before joining the queue. Call this after init() resolves and before joinQueue().

`joinQueue()`

widget.joinQueue(consents?: Record<string, boolean>): Promise<QueueTicket>

Places the visitor in the support queue. Pass any consent flags collected from your pre-call form (e.g. terms, recording).

Returns a QueueTicket:

interface QueueTicket {
  ticket_id: string;
  position: number;
}

Throws if the widget is already queued or if the visitor is currently in a call or assigned to an agent.

`leaveQueue()`

widget.leaveQueue(): Promise<void>

Removes the visitor from the queue and emits queue:left.

`getQueuePosition()`

widget.getQueuePosition(): number | null

Returns the current queue position, or null if the visitor is not in a queue.

`endSession()`

widget.endSession(): Promise<void>

Ends the active video session. Also stops cobrowsing if it is running.

`stopCobrowsing()`

widget.stopCobrowsing(): Promise<void>

Stops the cobrowsing session without ending the call.

`getState()`

widget.getState(): WidgetState

Returns the current widget state:

type WidgetState =
  | "idle"
  | "initializing"
  | "ready"
  | "submitting"
  | "queued"
  | "assigned"
  | "in_call"
  | "ended"
  | "error";

`getCurrentAgent()`

widget.getCurrentAgent(): Agent | null

Returns the currently assigned agent, or null if none has been assigned.

interface Agent {
  id: string;
  name: string;
  avatar_url?: string;
}

`on()`

widget.on<K extends keyof EventMap>(event: K, callback: (...args: EventMap[K]) => void): void

Subscribes to a widget event. See Events below for all available events.

`off()`

widget.off<K extends keyof EventMap>(event: K, callback: (...args: EventMap[K]) => void): void

Removes a previously registered event listener.

`executeJitsiCommand()`

widget.executeJitsiCommand(command: string, ...args: any[]): void

Executes a video call command on the active video conference. Common commands:

Command	Effect
`toggleAudio`	Mute / unmute the microphone
`toggleVideo`	Enable / disable the camera
`hangup`	End the conference

`destroy()`

widget.destroy(): void

Cleans up all resources: stops cursor tracking, closes realtime channels, destroys internal managers, and emits destroyed. Always call this on component unmount.

Events

Subscribe with widget.on(event, handler) and unsubscribe with widget.off(event, handler).

Lifecycle

Event	Payload	Description
`ready`	—	SDK initialised and ready
`destroyed`	—	`destroy()` was called and all resources cleaned up

Queue

Event	Payload	Description
`queue:joined`	`QueueTicket`	Visitor entered the queue
`queue:update`	`number`	Queue position changed
`queue:left`	—	Visitor left the queue

Call

Event	Payload	Description
`agent:assigned`	`Agent`	An agent accepted the session
`call:ready`	`SessionInfo`	Session info available; call UI can be rendered
`call:started`	—	Video call is live
`call:ended`	—	Video call finished

Cobrowsing

Event	Payload	Description
`cobrowse:invitation`	—	Agent requested cobrowsing
`cobrowse:consent:required`	`CobrowsingConsentHandlers`	Consent prompt should be shown to the visitor
`cobrowse:started`	—	Cobrowsing session started
`cobrowse:stopped`	—	Cobrowsing stopped without ending the session
`cobrowse:ended`	—	Cobrowsing session ended

Agent cursor

Event	Payload	Description
`agent:cursor:move`	`CursorPosition`	Agent cursor moved
`agent:cursor:click`	`CursorPosition`	Agent clicked
`agent:cursor:visible`	`boolean`	Cursor visibility changed

Error

Event	Payload	Description
`error`	`Error`	An unhandled error occurred

Troubleshooting Common errors, HTTP status codes, and how to fix them.