Widget web SDK: Referencia de la API

integrationId

Obligatorio

Identificador público de integración copiado del canal de widget de DobroDesk.

string

launcher

Valor predeterminado: default

Opciones de navegación nativa y de presentación del launcher o panel web.

"default" | "hidden" = "default"

locale

Valor predeterminado: auto

Locale del widget para el contenido. La web usa auto de forma predeterminada; los bundles nativos admiten actualmente en, uk, de y es.

string? = "auto"

loaderUrl

Valor predeterminado: https://widget.dobrodesk.com/widget/loader/v1.min.js

URL del script loader versionado del navegador. Si se omite, se usa el loader alojado por DobroDesk.

string?

appearance

Objeto compartido appearance-v2: colores, tipografía, diseño y sombra dentro de los límites documentados.

DobroDeskWidgetAppearance?

appearanceElement

Objeto compartido appearance-v2: colores, tipografía, diseño y sombra dentro de los límites documentados.

HTMLElement?

container

Opciones de navegación nativa y de presentación del launcher o panel web.

HTMLElement?

identityToken

Una función del backend que devuelve un JWT de cliente firmado y de corta duración. El secreto nunca va en la aplicación.

string?

helpCenterHandoffToken

Actualiza una identidad firmada de corta duración o un token de transferencia al Help Center.

string?

openOnReady

Valor predeterminado: false

Opciones de navegación nativa y de presentación del launcher o panel web.

boolean?

previewContext

Contexto JSON limitado proporcionado a acciones del host registradas explícitamente.

DobroDeskWidgetPreviewContext?

prefill

Contexto JSON limitado proporcionado a acciones del host registradas explícitamente.

DobroDeskWidgetPrefill?

context

Contexto JSON limitado proporcionado a acciones del host registradas explícitamente.

DobroDeskWidgetContext?

hostActions

Callbacks permitidos de la aplicación para acciones guiadas del widget. No autentican solicitudes de red.

Record<string, DobroDeskWidgetHostActionHandler>?

createDobroDeskWidget

Crea el cliente y valida la configuración.

createDobroDeskWidget(options: DobroDeskWidgetOptions) -> DobroDeskWidgetClient

Errores

• widget_context_invalid
• widget_mount_container_invalid
• widget_appearance_invalid

ready

Se resuelve cuando terminan la carga del loader web y el handshake con el frame.

ready: Promise<void>

open / close / toggle

Abre el panel del widget.

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

hide / show

Oculta la presentación del widget.

hide(): void; show(): void

logout

Finaliza la sesión y libera capacidades opcionales.

logout(): void

destroy

Destruye el page widget y libera la instancia activa.

destroy(): void

setLauncherVisibility

Muestra u oculta el launcher integrado sin cerrar el widget.

setLauncherVisibility(visible: boolean): void

setLocale

Cambia el locale del widget.

setLocale(locale: string): void

prefill

Establece los datos del cliente antes de iniciar la conversación.

prefill(value: DobroDeskWidgetPrefill): void

setIdentityToken

Actualiza una identidad firmada de corta duración o un token de transferencia al Help Center.

setIdentityToken(token: string): void

setHelpCenterHandoffToken

Actualiza una identidad firmada de corta duración o un token de transferencia al Help Center.

setHelpCenterHandoffToken(token: string): void

setPreviewContext

Establece el contexto de vista previa del operador en memoria para el loader web.

setPreviewContext(context: DobroDeskWidgetPreviewContext): void

openHelp / openArticle

Abre la vista de Help del widget.

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

requestHuman

Solicita la transferencia configurada a una persona.

requestHuman(): void

setContext / getContext

Reemplaza el contexto limitado de las acciones del host.

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

updateAppearance

Aplica un override de apariencia validado en tiempo de ejecución.

updateAppearance(appearance: DobroDeskWidgetAppearance): void

Errores

• widget_appearance_invalid

resetAppearance

Restablece la apariencia de ejecución a los valores del administrador o proporcionados.

resetAppearance(appearance?: DobroDeskWidgetAppearance): void

refreshAppearance

Vuelve a leer las variables CSS del host y aplica valores dentro de los límites.

refreshAppearance(hostElement?: HTMLElement): void

getAppearance

Devuelve la apariencia efectiva y el origen de sus campos.

getAppearance(): DobroDeskWidgetAppearanceSnapshot | null

getState

Devuelve el estado actual del widget sin suscribirse.

getState(): DobroDeskWidgetState

DobroDeskWidgetLoadingState

El estado de carga compartido es idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting o 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

Los eventos nativos y de wrappers usan el envelope compartido de carga, sesión, snapshot, mensaje aceptado, error y sesión eliminada.

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

onStateChange

Notifica al host cuando cambia el estado del widget.

onStateChange(listener): () => void

onLoadingChange

Notifica al host las fases de carga y reconexión.

onLoadingChange(listener): () => void

on / off

Se suscribe a un evento del widget por nombre.

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

DobroDeskWidgetErrorCode

Gestiona códigos estables legibles por máquinas y mantén los diagnósticos del servidor fuera de la interfaz del cliente.

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