Web widget SDK: API reference

integrationId

Required

The public integration identifier copied from the DobroDesk widget channel.

string

launcher

Default: default

Native navigation and web launcher or panel presentation options.

"default" | "hidden" = "default"

locale

Default: auto

The widget locale used for content. Web defaults to auto; native widget bundles currently support en, uk, de and es.

string? = "auto"

loaderUrl

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

The versioned browser loader script URL. Leave it unset to use the DobroDesk hosted loader.

string?

appearance

The shared appearance-v2 object: colors, typography, layout and shadow within documented bounds.

DobroDeskWidgetAppearance?

appearanceElement

The shared appearance-v2 object: colors, typography, layout and shadow within documented bounds.

HTMLElement?

container

Native navigation and web launcher or panel presentation options.

HTMLElement?

identityToken

A host backend function that returns a short-lived signed customer JWT. Keep its signing secret out of the app.

string?

helpCenterHandoffToken

Updates a short-lived signed identity or Help Center handoff token.

string?

openOnReady

Default: false

Native navigation and web launcher or panel presentation options.

boolean?

previewContext

Bounded JSON context supplied to explicitly registered host actions.

DobroDeskWidgetPreviewContext?

prefill

Bounded JSON context supplied to explicitly registered host actions.

DobroDeskWidgetPrefill?

context

Bounded JSON context supplied to explicitly registered host actions.

DobroDeskWidgetContext?

hostActions

Allowlisted application callbacks for guided widget actions. They do not authenticate network requests.

Record<string, DobroDeskWidgetHostActionHandler>?

createDobroDeskWidget

Creates the client and validates the integration configuration.

createDobroDeskWidget(options: DobroDeskWidgetOptions) -> DobroDeskWidgetClient

Errors

• widget_context_invalid
• widget_mount_container_invalid
• widget_appearance_invalid

ready

Resolves after the web loader and frame handshake complete.

ready: Promise<void>

open / close / toggle

Opens the widget panel.

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

hide / show

Hides the widget presentation.

hide(): void; show(): void

logout

Ends the active customer session and disposes optional capability state.

logout(): void

destroy

Destroys the page widget and releases the active instance.

destroy(): void

setLauncherVisibility

Shows or hides the built-in launcher without closing the widget.

setLauncherVisibility(visible: boolean): void

setLocale

Changes the widget locale.

setLocale(locale: string): void

prefill

Sets customer fields before the conversation starts.

prefill(value: DobroDeskWidgetPrefill): void

setIdentityToken

Updates a short-lived signed identity or Help Center handoff token.

setIdentityToken(token: string): void

setHelpCenterHandoffToken

Updates a short-lived signed identity or Help Center handoff token.

setHelpCenterHandoffToken(token: string): void

setPreviewContext

Sets the memory-only operator preview context used by the web loader.

setPreviewContext(context: DobroDeskWidgetPreviewContext): void

openHelp / openArticle

Opens the widget Help view.

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

requestHuman

Requests the configured human handoff.

requestHuman(): void

setContext / getContext

Replaces bounded host-action context.

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

updateAppearance

Applies a validated runtime appearance override.

updateAppearance(appearance: DobroDeskWidgetAppearance): void

Errors

• widget_appearance_invalid

resetAppearance

Resets runtime appearance to admin or supplied values.

resetAppearance(appearance?: DobroDeskWidgetAppearance): void

refreshAppearance

Re-reads host CSS variables and applies bounded values.

refreshAppearance(hostElement?: HTMLElement): void

getAppearance

Returns effective appearance and field sources.

getAppearance(): DobroDeskWidgetAppearanceSnapshot | null

getState

Returns the current widget state without subscribing.

getState(): DobroDeskWidgetState

DobroDeskWidgetLoadingState

The shared loading state is one of idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting or 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 and wrapper events use the shared loading, session, snapshot, accepted-message, error and session-cleared envelope.

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

onStateChange

Notifies the host when widget state changes.

onStateChange(listener): () => void

onLoadingChange

Notifies the host about loading and reconnecting phases.

onLoadingChange(listener): () => void

on / off

Subscribes to a named widget event.

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

DobroDeskWidgetErrorCode

Handle stable machine-readable codes and keep server diagnostics out of customer UI.

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