Widget web SDK: Referência da API

integrationId

Obrigatório

Identificador público da integração copiado do canal do widget DobroDesk.

string

launcher

Valor padrão: default

Opções de navegação nativa e de apresentação do launcher ou painel web.

"default" | "hidden" = "default"

locale

Valor padrão: auto

Locale do widget para o conteúdo. A web usa auto por padrão; os bundles nativos aceitam atualmente en, uk, de e es.

string? = "auto"

loaderUrl

Valor padrão: https://widget.dobrodesk.com/widget/loader/v1.min.js

URL do script loader versionado do navegador. Se omitida, o loader hospedado pela DobroDesk é usado.

string?

appearance

Objeto compartilhado appearance-v2: cores, tipografia, layout e sombra dentro dos limites documentados.

DobroDeskWidgetAppearance?

appearanceElement

Objeto compartilhado appearance-v2: cores, tipografia, layout e sombra dentro dos limites documentados.

HTMLElement?

container

Opções de navegação nativa e de apresentação do launcher ou painel web.

HTMLElement?

identityToken

Uma função do backend que retorna um JWT de cliente assinado e de curta duração. O segredo fica fora do aplicativo.

string?

helpCenterHandoffToken

Atualiza uma identidade assinada de curta duração ou um token de transferência para o Help Center.

string?

openOnReady

Valor padrão: false

Opções de navegação nativa e de apresentação do launcher ou painel web.

boolean?

previewContext

Contexto JSON limitado fornecido a ações do host registradas explicitamente.

DobroDeskWidgetPreviewContext?

prefill

Contexto JSON limitado fornecido a ações do host registradas explicitamente.

DobroDeskWidgetPrefill?

context

Contexto JSON limitado fornecido a ações do host registradas explicitamente.

DobroDeskWidgetContext?

hostActions

Callbacks permitidos do aplicativo para ações guiadas do widget. Eles não autenticam solicitações de rede.

Record<string, DobroDeskWidgetHostActionHandler>?

createDobroDeskWidget

Cria o cliente e valida a configuração.

createDobroDeskWidget(options: DobroDeskWidgetOptions) -> DobroDeskWidgetClient

Erros

• widget_context_invalid
• widget_mount_container_invalid
• widget_appearance_invalid

ready

É resolvido quando o carregamento do loader web e o handshake com o frame terminam.

ready: Promise<void>

open / close / toggle

Abre o painel do widget.

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

hide / show

Oculta a apresentação do widget.

hide(): void; show(): void

logout

Encerra a sessão e libera recursos opcionais.

logout(): void

destroy

Destrói o page widget e libera a instância ativa.

destroy(): void

setLauncherVisibility

Mostra ou oculta o launcher integrado sem fechar o widget.

setLauncherVisibility(visible: boolean): void

setLocale

Altera o locale do widget.

setLocale(locale: string): void

prefill

Define os dados do cliente antes do início da conversa.

prefill(value: DobroDeskWidgetPrefill): void

setIdentityToken

Atualiza uma identidade assinada de curta duração ou um token de transferência para o Help Center.

setIdentityToken(token: string): void

setHelpCenterHandoffToken

Atualiza uma identidade assinada de curta duração ou um token de transferência para o Help Center.

setHelpCenterHandoffToken(token: string): void

setPreviewContext

Define o contexto de pré-visualização do operador mantido apenas em memória para o loader web.

setPreviewContext(context: DobroDeskWidgetPreviewContext): void

openHelp / openArticle

Abre a visualização de Help do widget.

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

requestHuman

Solicita a transferência configurada para uma pessoa.

requestHuman(): void

setContext / getContext

Substitui o contexto limitado das ações do host.

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

updateAppearance

Aplica um override validado de aparência em tempo de execução.

updateAppearance(appearance: DobroDeskWidgetAppearance): void

Erros

• widget_appearance_invalid

resetAppearance

Restaura a aparência de execução para os valores do administrador ou fornecidos.

resetAppearance(appearance?: DobroDeskWidgetAppearance): void

refreshAppearance

Lê novamente as variáveis CSS do host e aplica valores dentro dos limites.

refreshAppearance(hostElement?: HTMLElement): void

getAppearance

Retorna a aparência efetiva e a origem de seus campos.

getAppearance(): DobroDeskWidgetAppearanceSnapshot | null

getState

Retorna o estado atual do widget sem assinar eventos.

getState(): DobroDeskWidgetState

DobroDeskWidgetLoadingState

O estado de carregamento partilhado é idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting ou 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

Eventos nativos e de wrappers usam o envelope compartilhado de carregamento, sessão, snapshot, mensagem aceita, erro e sessão limpa.

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

onStateChange

Notifica o host quando o estado do widget muda.

onStateChange(listener): () => void

onLoadingChange

Notifica o host sobre as fases de carregamento e reconexão.

onLoadingChange(listener): () => void

on / off

Assina um evento nomeado do widget.

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

DobroDeskWidgetErrorCode

Trate códigos estáveis legíveis por máquina e mantenha os diagnósticos do servidor fora da interface do 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