Web-Widget SDK: API-Referenz

integrationId

Erforderlich

Die öffentliche Integrationskennung aus dem DobroDesk-Widget-Kanal.

string

launcher

Standardwert: default

Optionen für native Navigation sowie die Darstellung des Web-Launchers oder Panels.

"default" | "hidden" = "default"

locale

Standardwert: auto

Widget-Locale für Inhalte. Web verwendet standardmäßig auto; native Widget-Bundles unterstützen derzeit en, uk, de und es.

string? = "auto"

loaderUrl

Standardwert: https://widget.dobrodesk.com/widget/loader/v1.min.js

URL des versionierten Browser-Loader-Skripts. Ohne Angabe wird der von DobroDesk gehostete Loader verwendet.

string?

appearance

Das gemeinsame appearance-v2-Objekt mit Farben, Typografie, Layout und Schatten innerhalb der dokumentierten Grenzen.

DobroDeskWidgetAppearance?

appearanceElement

Das gemeinsame appearance-v2-Objekt mit Farben, Typografie, Layout und Schatten innerhalb der dokumentierten Grenzen.

HTMLElement?

container

Optionen für native Navigation sowie die Darstellung des Web-Launchers oder Panels.

HTMLElement?

identityToken

Eine Backend-Funktion für ein kurzlebiges signiertes Kunden-JWT. Das Signiergeheimnis bleibt außerhalb der App.

string?

helpCenterHandoffToken

Aktualisiert eine kurzlebige signierte Identität oder ein Übergabetoken für das Help Center.

string?

openOnReady

Standardwert: false

Optionen für native Navigation sowie die Darstellung des Web-Launchers oder Panels.

boolean?

previewContext

Begrenzter JSON-Kontext für ausdrücklich registrierte Host-Aktionen.

DobroDeskWidgetPreviewContext?

prefill

Begrenzter JSON-Kontext für ausdrücklich registrierte Host-Aktionen.

DobroDeskWidgetPrefill?

context

Begrenzter JSON-Kontext für ausdrücklich registrierte Host-Aktionen.

DobroDeskWidgetContext?

hostActions

Freigegebene Anwendungs-Callbacks für geführte Widget-Aktionen. Sie authentifizieren keine Netzwerkanfragen.

Record<string, DobroDeskWidgetHostActionHandler>?

createDobroDeskWidget

Erstellt den Client und prüft die Integrationskonfiguration.

createDobroDeskWidget(options: DobroDeskWidgetOptions) -> DobroDeskWidgetClient

Fehler

• widget_context_invalid
• widget_mount_container_invalid
• widget_appearance_invalid

ready

Wird aufgelöst, sobald Browser-Loader und Frame-Handshake abgeschlossen sind.

ready: Promise<void>

open / close / toggle

Öffnet das Widget-Panel.

open(): void; close(): void; toggle(): void

hide / show

Blendet die Widget-Darstellung aus.

hide(): void; show(): void

logout

Beendet die Kundensitzung und optionale Funktionen.

logout(): void

destroy

Zerstört das Page-Widget und gibt die aktive Instanz frei.

destroy(): void

setLauncherVisibility

Zeigt oder verbirgt den integrierten Launcher, ohne das Widget zu schließen.

setLauncherVisibility(visible: boolean): void

setLocale

Ändert die Widget-Locale.

setLocale(locale: string): void

prefill

Setzt Kundendaten vor dem Beginn der Unterhaltung.

prefill(value: DobroDeskWidgetPrefill): void

setIdentityToken

Aktualisiert eine kurzlebige signierte Identität oder ein Übergabetoken für das Help Center.

setIdentityToken(token: string): void

setHelpCenterHandoffToken

Aktualisiert eine kurzlebige signierte Identität oder ein Übergabetoken für das Help Center.

setHelpCenterHandoffToken(token: string): void

setPreviewContext

Setzt den nur im Speicher gehaltenen Operator-Vorschaukontext für den Web-Loader.

setPreviewContext(context: DobroDeskWidgetPreviewContext): void

openHelp / openArticle

Öffnet die Help-Ansicht des Widgets.

openHelp(): void; openArticle(articleId: string): void

requestHuman

Fordert die konfigurierte Übergabe an einen Menschen an.

requestHuman(): void

setContext / getContext

Ersetzt den begrenzten Kontext für Host-Aktionen.

setContext(value): void; getContext(): DobroDeskWidgetContext

updateAppearance

Wendet eine validierte Laufzeitüberschreibung der Darstellung an.

updateAppearance(appearance: DobroDeskWidgetAppearance): void

Fehler

• widget_appearance_invalid

resetAppearance

Setzt die Laufzeitdarstellung auf Admin- oder bereitgestellte Werte zurück.

resetAppearance(appearance?: DobroDeskWidgetAppearance): void

refreshAppearance

Liest Host-CSS-Variablen erneut ein und wendet begrenzte Werte an.

refreshAppearance(hostElement?: HTMLElement): void

getAppearance

Liefert die effektive Darstellung und die Quellen ihrer Felder.

getAppearance(): DobroDeskWidgetAppearanceSnapshot | null

getState

Liefert den aktuellen Widget-Status ohne Abonnement.

getState(): DobroDeskWidgetState

DobroDeskWidgetLoadingState

Der gemeinsame Ladezustand ist idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting oder flushing-outbox.

{ active: boolean; phase: idle | initializing | loading-content | loading-session | sending-message | waiting-for-response | executing-action | reconnecting | error; operationId?; kind?; scope?; requestId?; actionId?; startedAt?; errorCode? }

DobroDeskWidgetEventType

Native und Wrapper-Ereignisse verwenden das gemeinsame Envelope für Laden, Sitzung, Snapshot, akzeptierte Nachricht, Fehler und gelöschte Sitzung.

opened | closed | conversationStarted | messageSent | messageReceived | formSubmitted | handoffRequested | handoffStateChanged | unreadCountChanged | actionProposed | actionConfirmed | actionCompleted | actionFailed | hostActionRequested | stateChanged | loadingChanged

onStateChange

Informiert den Host über Änderungen des Widget-Status.

onStateChange(listener): () => void

onLoadingChange

Informiert den Host über Lade- und Wiederverbindungsphasen.

onLoadingChange(listener): () => void

on / off

Abonniert ein Widget-Ereignis mit dem angegebenen Namen.

on(eventType, listener): () => void; off(eventType, listener): void

DobroDeskWidgetErrorCode

Behandeln Sie stabile maschinenlesbare Codes und halten Sie Serverdiagnosen aus der Kundenoberfläche fern.

widget_ready_timeout | widget_context_invalid | widget_mount_container_invalid | widget_appearance_invalid | host_action_failed | host_action_invalid_result | host_action_timeout | widget_logged_out | widget_identity_changed | widget_destroyed