NativeScript SDK: Referência da API

DobroDeskSdkConfig

Obrigatório

A configuração do framework fornece a identidade do aplicativo e o escopo da conta e obtém um token de autorização novo e de curta duração do provedor de credenciais do host. As formas do token e do resultado seguem a assinatura da plataforma exibida.

{ apiOrigin: string; integrationId: string; accountScope: string; locale?: SdkLocale; turnstileToken?: string; pollIntervalMs?: number; fetchImpl?: typeof fetch; credentialProvider: () => Promise<{ authorizationToken: string }>; hostActions?: HostActionHandlers; context?: JsonObject }

Erros

• invalid-config

DobroDeskNativeScriptClient

Cria o cliente e valida a configuração.

new DobroDeskNativeScriptClient(bridge, config: DobroDeskSdkConfig)

createDobroDeskNativeScriptClient

Cria o cliente e valida a configuração.

createDobroDeskNativeScriptClient(config: DobroDeskSdkConfig): DobroDeskNativeScriptClient

startSession

Inicia uma conversa com uma primeira mensagem idempotente.

startSession(message: string, options?: Omit<SessionStartInput, 'message'>): Promise<unknown>

Erros

• network
• field-invalid
• idempotency-conflict
• outbox-corrupt

resumeSession

Restaura o estado da conta ou uma sessão do servidor.

resumeSession(): Promise<unknown>

Erros

• network
• session-expired
• outbox-corrupt

refresh

Carrega o estado atual da conversa.

refresh(): Promise<unknown>

Erros

• network
• session-expired
• message-rejected

waitForAssistant

Consulta com tempo limitado até o trabalho do assistente terminar ou a espera expirar.

waitForAssistant(options?: Omit<WaitForAssistantOptions, 'pollIntervalMs'>): Promise<unknown>

Erros

• realtime-unavailable
• network
• session-expired

sendMessage

Envia uma mensagem e retorna o status de entrega.

sendMessage(text: string, idempotencyKey?: string): Promise<unknown>

Erros

• network
• idempotency-conflict
• conversation-stale
• rate-limited
• message-rejected

flushOutbox

Reenvia mutações pendentes com o corpo e a chave originais.

flushOutbox(): Promise<unknown>

Erros

• network
• outbox-corrupt
• session-expired

resetSession

Limpa a sessão, o snapshot e as mutações pendentes associados à conta.

resetSession(): Promise<unknown>

Erros

• request-in-progress
• outbox-corrupt

setAuthorizationToken

Fornece à ponte nativa o token de curta duração mais recente.

setAuthorizationToken(token: string): Promise<unknown>

logout

Encerra a sessão e libera recursos opcionais.

logout(): Promise<unknown>

Erros

• outbox-corrupt

presentWidget

Apresenta o widget nativo com o contrato compartilhado.

presentWidget(options?: NativeWidgetOptions): Promise<unknown>

Erros

• invalid-config
• request-in-progress
• field-invalid

closeWidget

Fecha a apresentação nativa atual ou libera um host montado.

closeWidget(): Promise<unknown>

subscribe

Assina os eventos canônicos do SDK. Para liberar o listener, use a assinatura, o callback de cancelamento ou a assinatura do stream retornada pela plataforma.

subscribe(listener: (event: SdkEvent) => void): () => void

operations

Expõe operações tipadas de formulários, ferramentas do cliente, anexos e comércio pelo mecanismo nativo.

operations: DobroDeskRichOperations

submitForm

Envia valores limitados para um formulário de conversa fornecido pelo servidor. O identificador e os valores são validados antes da solicitação nativa assinada.

operations.submitForm(requestId: string, values: JsonObject): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• message-rejected

requestClientTool

Solicita uma ferramenta do cliente permitida, confirma o resultado ou consulta o estado. Os payloads são planos, limitados e rejeitam nomes de campos sensíveis.

operations.requestClientTool(input: ClientToolRequest): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• not_found

completeClientTool

Solicita uma ferramenta do cliente permitida, confirma o resultado ou consulta o estado. Os payloads são planos, limitados e rejeitam nomes de campos sensíveis.

operations.completeClientTool(input: ClientToolResult): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• not_found

clientToolStatus

Solicita uma ferramenta do cliente permitida, confirma o resultado ou consulta o estado. Os payloads são planos, limitados e rejeitam nomes de campos sensíveis.

operations.clientToolStatus(callId: string): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• not_found

procedureAction

Avança uma ação de procedimento fornecida pelo servidor com uma chave de idempotência e a revisão esperada do fluxo.

operations.procedureAction(input: ProcedureActionInput): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• message-rejected
• idempotency-conflict

attachmentIntents

Cria intents de upload e envia arquivos locais selecionados dentro dos limites de tamanho, tipo, URI e política do SDK.

operations.attachmentIntents(messageId: string, attachments: readonly AttachmentDescriptor[]): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• attachment_policy_failed
• attachment_rate_limited

uploadAttachment

Cria intents de upload e envia arquivos locais selecionados dentro dos limites de tamanho, tipo, URI e política do SDK.

operations.uploadAttachment(intent: AttachmentUploadIntent, fileUri: string, mimeType: string): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• attachment_policy_failed
• attachment_rate_limited

listOrders

Lê dados de pedidos e cria, confirma ou consulta uma proposta limitada para cancelar um pedido da Shopify.

operations.listOrders(query?: CommerceOrderQuery): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• commerce_identity_required
• commerce_unavailable
• shopify_reconnect_required
• shopify_rate_limited

orderDetail

Lê dados de pedidos e cria, confirma ou consulta uma proposta limitada para cancelar um pedido da Shopify.

operations.orderDetail(orderRef: string): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• commerce_identity_required
• commerce_unavailable
• not_found

createCommerceProposal

Lê dados de pedidos e cria, confirma ou consulta uma proposta limitada para cancelar um pedido da Shopify.

operations.createCommerceProposal(input: CommerceProposalInput, idempotencyKey: string): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• commerce_identity_required
• commerce_unavailable
• shopify_reconnect_required
• shopify_rate_limited
• idempotency-conflict

confirmCommerceProposal

Lê dados de pedidos e cria, confirma ou consulta uma proposta limitada para cancelar um pedido da Shopify.

operations.confirmCommerceProposal(proposalId: string, idempotencyKey: string): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• commerce_identity_required
• commerce_unavailable
• shopify_reconnect_required
• shopify_rate_limited
• not_found
• idempotency-conflict

commerceProposal

Lê dados de pedidos e cria, confirma ou consulta uma proposta limitada para cancelar um pedido da Shopify.

operations.commerceProposal(proposalId: string): Promise<JsonValue>

Retorna

Promise<JsonValue>

Erros

• field-invalid
• network
• http
• session-expired
• commerce_identity_required
• commerce_unavailable
• not_found

ClientToolRequest

Solicita uma ferramenta do cliente permitida, confirma o resultado ou consulta o estado. Os payloads são planos, limitados e rejeitam nomes de campos sensíveis.

{ toolName: string; basisMessageId: string; input: ClientToolPayload }

ClientToolResult

Solicita uma ferramenta do cliente permitida, confirma o resultado ou consulta o estado. Os payloads são planos, limitados e rejeitam nomes de campos sensíveis.

{ callId: string; output: ClientToolPayload }

AttachmentDescriptor

Cria intents de upload e envia arquivos locais selecionados dentro dos limites de tamanho, tipo, URI e política do SDK.

{ clientId: string; fileName: string; mimeType: string; sizeBytes: number; kind: AttachmentKind }

AttachmentUploadIntent

Cria intents de upload e envia arquivos locais selecionados dentro dos limites de tamanho, tipo, URI e política do SDK.

{ clientId: string; attachmentId: string; uploadUrl: string; uploadToken: string; expiresAt: string }

CommerceProposalInput

Lê dados de pedidos e cria, confirma ou consulta uma proposta limitada para cancelar um pedido da Shopify.

{ actionId: "shopify_order_cancel"; selection: { storeReference: string; orderReference: string; lineItems?: { lineItemReference: string; quantity: number }[] } }

DobroDeskLoadingState

O estado de carregamento partilhado é idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting ou flushing-outbox.

"idle" | "starting-session" | "loading-messages" | "sending-message" | "waiting-for-assistant" | "executing-action" | "reconnecting" | "flushing-outbox"

SdkEvent

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

loading(state: DobroDeskLoadingState) | session-cleared | session-started | snapshot | message-accepted | error | host-action-requested | host-action-cancelled

WidgetExperience

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

schemaVersion, locale, appearance, platformOverrides, presentation, reducedMotion, copy

Erros

• field-invalid
• unsupported

createWidgetView

Apresenta o widget nativo com o contrato compartilhado.

createWidgetView(options?: NativeScriptWidgetViewOptions): NativeScriptWidgetView

Erros

• invalid-config
• request-in-progress
• field-invalid

DobroDeskNativeScriptWidgetView

Apresenta o widget nativo com o contrato compartilhado.

ContentView; isOpen: boolean; open(): Promise<void>; close(): Promise<void>; release(): Promise<void>

onLoadingChange

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

onLoadingChange(loading: boolean): void

NativeOperation (wrapper bridge)

Expõe operações tipadas de formulários, ferramentas do cliente, anexos e comércio pelo mecanismo nativo.

operation: "complete-host-action" | "request-client-tool" | "complete-client-tool" | "client-tool-status" | "submit-form" | "procedure-action" | "attachment-intents" | "upload-attachment" | "list-orders" | "order-detail" | "create-commerce-proposal" | "confirm-commerce-proposal" | "commerce-proposal"

complete-host-action (local bridge)

As pontes de framework codificam a conclusão de uma ação do host por uma ponte nativa local. Ela não é enviada como uma operação HTTP pelo cliente nativo direto.

{ operation: "complete-host-action"; requestId: string; actionId: string; result: HostActionResult }

Retorna

JsonValue

Erros

• field-invalid
• session-expired
• unsupported

attachVoice

Conecta o recurso de voz opcional instalado pelo host.

attachVoice(port: DobroDeskVoicePort): Promise<DobroDeskVoiceFacade>

Erros

• unsupported
• invalid-config

voice

Controla um recurso de voz opcional instalado pelo host: iniciar, parar, silenciar, barge-in e liberar recursos. O widget web pode mostrar uma interface de voz, mas esta API do SDK controla apenas uma ponte de voz fornecida pelo host.

voice: DobroDeskVoiceFacade | undefined

createNativeScriptVoicePort

Conecta o recurso de voz opcional instalado pelo host.

createNativeScriptVoicePort(bridge): DobroDeskVoicePort

voice lifecycle

Controla um recurso de voz opcional instalado pelo host: iniciar, parar, silenciar, barge-in e liberar recursos. O widget web pode mostrar uma interface de voz, mas esta API do SDK controla apenas uma ponte de voz fornecida pelo host.

start(): Promise<void>; stop(): Promise<void>; setMuted(muted: boolean): Promise<void>; bargeIn(): Promise<void>; dispose(): Promise<void>

Erros

• invalid-configuration
• permission-denied
• audio-unavailable
• session-expired
• realtime-unavailable
• invalid-response
• protocol-violation
• stale-frame
• queue-overloaded
• cancelled
• unsupported

push module (native only)

Descreve o artefato push nativo opcional e o registo do host. Os wrappers de framework não exportam um cliente push JavaScript ou Dart; use o módulo nativo iOS ou Android.

No JS/Dart wrapper export; use the iOS DobroDeskPush product or Android com.dobrodesk:dobrodesk-push:<version>.

SdkErrorCode

Trate códigos estáveis legíveis por máquina e mantenha os diagnósticos do servidor fora da interface do cliente.

invalid-config | network | http | integration-disabled | integration-paused | origin-not-allowed | turnstile-required | turnstile-failed | request-in-progress | idempotency-conflict | conversation-limit-reached | rate-limited | payload-too-large | field-invalid | conversation-stale | session-expired | realtime-unavailable | message-rejected | outbox-corrupt | unsupported