WidgetClient API-Referenz

WidgetClient ist die Hauptklasse, die von @univerx/client-sdk exportiert wird. Sie verwaltet den vollständigen Lebenszyklus einer Besuchersitzung: Authentifizierung, Warteschlange, Videoanruf und Cobrowsing.

Konstruktor

new WidgetClient(config: WidgetConfig)

Löst einen Fehler aus, wenn widgetKey nicht bereitgestellt wird. Kann sicher in SSR-/Server-Umgebungen aufgerufen werden — die Browser-Umgebungsprüfung wird auf init() verschoben. Siehe Konfiguration für die vollständige WidgetConfig-Referenz.

Methoden

`init()`

widget.init(): Promise<void>

Authentifiziert sich mit der Univerx-API, richtet Echtzeit-Kanäle ein und startet Cursor-Tracking. Muss vor jeder anderen Methode aufgerufen werden. Emittiert ready bei Erfolg und setzt den Status auf error bei Fehler.

Löst einen Fehler aus, wenn er außerhalb einer Browser-Umgebung oder mehr als einmal auf derselben Instanz aufgerufen wird.

`submitForm()`

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

Übermittelt Formulardaten vor dem Anruf (z.B. Name des Besuchers, E-Mail, Problemtyp), bevor die Warteschlange betreten wird. Rufen Sie dies auf, nachdem init() abgeschlossen ist und bevor joinQueue() aufgerufen wird.

`joinQueue()`

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

Platziert den Besucher in der Support-Warteschlange. Übergeben Sie alle Zustimmungs-Flags, die von Ihrem Formular vor dem Anruf gesammelt wurden (z.B. terms, recording).

Gibt ein QueueTicket zurück:

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

Löst einen Fehler aus, wenn das Widget bereits in der Warteschlange ist oder wenn der Besucher sich derzeit in einem Anruf befindet oder einem Agenten zugewiesen ist.

`leaveQueue()`

widget.leaveQueue(): Promise<void>

Entfernt den Besucher aus der Warteschlange und emittiert queue:left.

`getQueuePosition()`

widget.getQueuePosition(): number | null

Gibt die aktuelle Warteschlangenposition zurück oder null, wenn der Besucher nicht in einer Warteschlange ist.

`endSession()`

widget.endSession(): Promise<void>

Beendet die aktive Videositzung. Stoppt auch Cobrowsing, falls es läuft.

`stopCobrowsing()`

widget.stopCobrowsing(): Promise<void>

Stoppt die Cobrowsing-Sitzung, ohne den Anruf zu beenden.

`getState()`

widget.getState(): WidgetState

Gibt den aktuellen Widget-Status zurück:

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

`getCurrentAgent()`

widget.getCurrentAgent(): Agent | null

Gibt den aktuell zugewiesenen Agenten zurück oder null, wenn keiner zugewiesen wurde.

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

`on()`

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

Abonniert ein Widget-Event. Siehe Events unten für alle verfügbaren Events.

`off()`

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

Entfernt einen zuvor registrierten Event-Listener.

`executeJitsiCommand()`

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

Führt einen Videoanruf-Befehl auf der aktiven Videokonferenz aus. Häufige Befehle:

Befehl	Wirkung
`toggleAudio`	Mikrofon stummschalten / Stummschaltung aufheben
`toggleVideo`	Kamera aktivieren / deaktivieren
`hangup`	Konferenz beenden

`destroy()`

widget.destroy(): void

Bereinigt alle Ressourcen: stoppt Cursor-Tracking, schließt Echtzeit-Kanäle, zerstört interne Manager und emittiert destroyed. Rufen Sie dies immer beim Component Unmount auf.

Events

Abonnieren Sie mit widget.on(event, handler) und deabonnieren Sie mit widget.off(event, handler).

Lebenszyklus

Event	Payload	Beschreibung
`ready`	—	SDK initialisiert und bereit
`destroyed`	—	`destroy()` wurde aufgerufen und alle Ressourcen wurden bereinigt
`token:refreshed`	—	Sitzungs-Token wurde automatisch erneuert
`token:expired`	—	Token-Erneuerung fehlgeschlagen; die Sitzung kann keine authentifizierten Anfragen mehr stellen — neu initialisieren

Warteschlange

Event	Payload	Beschreibung
`queue:joined`	`QueueTicket`	Besucher ist der Warteschlange beigetreten
`queue:update`	`number`	Warteschlangenposition hat sich geändert
`queue:left`	—	Besucher hat die Warteschlange verlassen

Anruf

Event	Payload	Beschreibung
`agent:assigned`	`Agent`	Ein Agent hat die Sitzung akzeptiert
`call:ready`	`SessionInfo`	Sitzungsinformationen verfügbar; Anruf-UI kann gerendert werden
`call:started`	—	Videoanruf ist aktiv
`call:ended`	—	Videoanruf beendet

Cobrowsing

Event	Payload	Beschreibung
`cobrowse:invitation`	—	Agent hat Cobrowsing angefordert
`cobrowse:consent:required`	`CobrowsingConsentHandlers`	Zustimmungsaufforderung sollte dem Besucher angezeigt werden
`cobrowse:started`	—	Cobrowsing-Sitzung gestartet
`cobrowse:stopped`	—	Cobrowsing gestoppt, ohne die Sitzung zu beenden
`cobrowse:ended`	—	Cobrowsing-Sitzung beendet

Agenten-Cursor

Event	Payload	Beschreibung
`agent:cursor:move`	`CursorPosition`	Agenten-Cursor bewegt
`agent:cursor:click`	`CursorPosition`	Agent hat geklickt
`agent:cursor:visible`	`boolean`	Cursor-Sichtbarkeit hat sich geändert

Fehler

Event	Payload	Beschreibung
`error`	`Error`	Ein unbehandelter Fehler ist aufgetreten

Fehlerbehebung Häufige Fehler, HTTP-Statuscodes und wie Sie sie beheben.