Android SDK: Referência da API

apiOrigin

Obrigatório

A origem da API usa HTTPS em produção. Os clientes nativos permitem HTTP em localhost para desenvolvimento.

URL | String

integrationId

Obrigatório

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

String

accountScope

Obrigatório

Chave estável do cliente ou da conta que isola o estado persistente da sessão e da caixa de saída.

String

locale

Valor padrão: en

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 = "en"

credentialProvider

Obrigatório

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

() async throws -> String | suspend () -> String

turnstileToken

Token Turnstile opcional para integrações que precisam dele.

String?

pollInterval

Valor padrão: 1s

Intervalo limitado usado ao consultar uma resposta assíncrona do assistente.

TimeInterval | Duration = 1s

DobroDeskClient

Cria o cliente e valida a configuração.

DobroDeskClient(configuration: DobroDeskConfiguration, transport: DobroDeskTransport = ..., outbox: DobroDeskDurableStateStore, attachmentStore: DobroDeskAttachmentStore? = ...)

Erros

• invalid-config
• outbox-corrupt

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: (SdkEvent) -> Unit): () -> Unit

state getters

Retorna o estado atual do widget sem assinar eventos.

currentSession(), currentConfiguration(), currentWidgetVoiceSettings(), currentWidgetConfiguration(), currentWidgetNavigation(), currentWidgetContent(), currentSnapshot(), currentLoadingState(), shouldWaitForAssistant()

loadWidgetAppearance

Carrega o bundle validado de aparência ou conteúdo para o widget nativo.

loadWidgetAppearance(): JsonObject suspend

Erros

• network
• http
• session-expired

loadWidgetContent

Carrega o bundle validado de aparência ou conteúdo para o widget nativo.

loadWidgetContent(locale: String = configuration.locale): WidgetContentSnapshot suspend

Erros

• network
• http
• field-invalid

startSession

Inicia uma conversa com uma primeira mensagem idempotente.

startSession(input: SessionStartInput): DobroDeskSession suspend

Erros

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

resumeSession

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

resumeSession(): DobroDeskSession? suspend

Erros

• network
• session-expired
• outbox-corrupt

restoreSession

Restaura uma prova de sessão aceita e carrega seu snapshot.

restoreSession(restored: DobroDeskSession): ConversationSnapshot suspend

Erros

• session-expired
• network

refresh

Carrega o estado atual da conversa.

refresh(): ConversationSnapshot suspend

Erros

• network
• session-expired
• message-rejected

waitForAssistant

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

waitForAssistant(timeout: Duration = Duration.ofSeconds(30), afterMessageCount: Int? = null): ConversationSnapshot suspend

Erros

• invalid-config
• realtime-unavailable
• network
• session-expired

sendMessage

Envia uma mensagem e retorna o status de entrega.

sendMessage(input: MessageInput): AcceptedMessage suspend

Erros

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

attachments

Envia uma mensagem e retorna o status de entrega.

sendMessageWithAttachments(input: MessageInput, attachments: List<DobroDeskAttachment>): AcceptedMessage suspend; uploadMessageAttachments(messageId: String, attachments: List<DobroDeskAttachment>): List<DobroDeskAttachmentUpload> suspend; retryPendingAttachmentSend(): AcceptedMessage suspend

Erros

• attachment_policy_failed
• attachment_rate_limited
• session-expired
• outbox-corrupt

performOperation / performNativeOperation

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

performNativeOperation(requestJson: String, resolveFile: suspend (String, String) -> DobroDeskAttachmentSource): String

Erros

• field-invalid
• unsupported
• session-expired
• http

NativeOperation

Retorna JSON decodificado pela ponte nativa de operações. Trate validação, transporte, expiração e rejeição do servidor como resultados explícitos.

operation: "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"

Erros

• field-invalid
• unsupported
• session-expired
• http

submit-form request

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.

{ operation: "submit-form"; requestId: string; values: JsonObject }

Retorna

JsonValue

Erros

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

request-client-tool request

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.

{ operation: "request-client-tool"; input: ClientToolRequest }

Retorna

JsonValue

Erros

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

complete-client-tool request

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.

{ operation: "complete-client-tool"; input: ClientToolResult }

Retorna

JsonValue

Erros

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

client-tool-status request

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.

{ operation: "client-tool-status"; callId: string }

Retorna

JsonValue

Erros

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

procedure-action request

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

{ operation: "procedure-action"; input: ProcedureActionInput }

Retorna

JsonValue

Erros

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

attachment-intents request

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

{ operation: "attachment-intents"; messageId: string; attachments: AttachmentDescriptor[] }

Retorna

JsonValue

Erros

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

upload-attachment request

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

{ operation: "upload-attachment"; intent: AttachmentUploadIntent; fileUri: string; mimeType: string }

Retorna

JsonValue

Erros

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

list-orders request

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

{ operation: "list-orders"; query?: CommerceOrderQuery }

Retorna

JsonValue

Erros

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

order-detail request

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

{ operation: "order-detail"; orderRef: string }

Retorna

JsonValue

Erros

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

create-commerce-proposal request

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

{ operation: "create-commerce-proposal"; input: CommerceProposalInput; idempotencyKey: string }

Retorna

JsonValue

Erros

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

confirm-commerce-proposal request

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

{ operation: "confirm-commerce-proposal"; proposalId: string; input: { confirmed: true }; idempotencyKey: string }

Retorna

JsonValue

Erros

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

commerce-proposal request

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

{ operation: "commerce-proposal"; proposalId: string }

Retorna

JsonValue

Erros

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

NativeOperationBridgeResult

Retorna JSON decodificado pela ponte nativa de operações. Trate validação, transporte, expiração e rejeição do servidor como resultados explícitos.

{ valueJson: string }

Retorna

JsonValue

Erros

• http

HostActionResult

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

{ ok: boolean; status: "acknowledged" | "completed" | "failed"; data?: JsonValue; code?: string; retryable?: boolean }

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 }

ProcedureActionInput

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

{ action: "start" | "answer" | "availability" | "select" | "calendar_date" | "back" | "confirm" | "decline"; value: string; idempotencyKey: string; procedureId?: string; locale?: "en" | "uk" | "de" | "es"; runId?: string; expectedUpdatedAt?: string; stepId?: string; parameterId?: string; timeZone?: string; nativeCommerceUi?: true }

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: "image" | "video" | "pdf" | "text" }

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 }

CommerceOrderQuery

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

{ cursor?: string; store?: 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 }[] } }

requestAttachmentIntents

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

requestAttachmentIntents(messageId: String, attachments: List<DobroDeskAttachment>) suspend -> List<DobroDeskAttachmentIntent>

Erros

• attachment_policy_failed
• session-expired
• network
• http

uploadAttachment

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

uploadAttachment(intent: DobroDeskAttachmentIntent, source: DobroDeskAttachmentSource) suspend -> DobroDeskAttachmentUpload

Erros

• attachment_policy_failed
• session-expired
• network
• http

downloadAttachment

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

downloadAttachment(downloadUrl: String, destination: OutputStream) suspend -> BinaryDownloadResponse

Erros

• attachment_policy_failed
• session-expired
• network
• http

canDownloadAttachment

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

canDownloadAttachment(downloadUrl: String): Boolean

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.

requestClientTool(requestInput: DobroDeskClientToolRequest) suspend -> DobroDeskClientToolResponse

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.

completeClientTool(result: DobroDeskClientToolResult) suspend -> DobroDeskClientToolResponse

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.

clientToolStatus(callId: String) suspend -> DobroDeskClientToolResponse

Erros

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

submitConversationForm

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.

submitConversationForm(requestId: String, values: Map<String, JsonElement>) suspend -> Unit

Erros

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

performProcedureAction

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

performProcedureAction(action: DobroDeskProcedureActionRequest) suspend -> Unit

Erros

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

loadCommerceOrders

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

loadCommerceOrders(storeReference: String? = null, cursor: String? = null) suspend -> JsonElement?

Erros

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

loadCommerceOrderDetail

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

loadCommerceOrderDetail(orderReference: String) suspend -> JsonElement?

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.

createCommerceProposal(input: JsonObject, idempotencyKey: String) suspend -> JsonElement?

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.

confirmCommerceProposal(proposalId: String, idempotencyKey: String) suspend -> JsonElement?

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.

commerceProposal(proposalId: String) suspend -> JsonElement?

Erros

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

flushOutbox

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

flushOutbox(): List<AcceptedMessage> suspend

Erros

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() suspend

Erros

• request-in-progress
• outbox-corrupt

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

reducedMotion

Por padrão, segue o sistema e as políticas nativas de acessibilidade, energia e temperatura.

system | always

WidgetLocaleCopies.forLocale

Carrega um mapa nativo incluído para os textos principais do widget. O catálogo valida esse contrato compartilhado e atualmente inclui en, uk, de e es; os rótulos derivados de procedimentos, funções e validação são separados.

WidgetLocaleCopies.forLocale(locale: String): Map<String, String>

Erros

• field-invalid

WidgetCopy(values)

Cria ou lê os textos compartilhados validados do widget. Valores desconhecidos, ausentes, vazios ou longos demais são rejeitados antes da renderização.

WidgetCopy(values: Map<String, String>): WidgetCopy

Erros

• field-invalid

WidgetCopy.requiredKeys

Cria ou lê os textos compartilhados validados do widget. Valores desconhecidos, ausentes, vazios ou longos demais são rejeitados antes da renderização.

Set<String>

WidgetCopy.text

Cria ou lê os textos compartilhados validados do widget. Valores desconhecidos, ausentes, vazios ou longos demais são rejeitados antes da renderização.

WidgetCopy.text(key: String): String

Erros

• field-invalid

WidgetExperience.decodeAndResolve

Decodifica e resolve o contrato de design compartilhado com overrides de plataforma, de textos e o estado do sistema do host para reduzir movimento.

WidgetExperience.decodeAndResolve(data: String, platform: String, osReducedMotion: Boolean, localeCopy: Map<String, String>): WidgetExperience

Retorna

WidgetExperience

Erros

• field-invalid
• unsupported

WidgetExperience.resolve

Decodifica e resolve o contrato de design compartilhado com overrides de plataforma, de textos e o estado do sistema do host para reduzir movimento.

WidgetExperience.resolve(input: WidgetExperienceInput, platform: String, osReducedMotion: Boolean, localeCopy: Map<String, String>): WidgetExperience

Retorna

WidgetExperience

Erros

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Apresenta o widget nativo com o contrato compartilhado.

present(activity: Activity, client: DobroDeskClient, options: JsonObject = {}): DobroDeskWidgetBridgePresenter

Erros

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

close / detach

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

close(): Unit; detach(): Unit

DobroDeskWidgetBridgePresenter.createEmbedded

Apresenta o widget nativo com o contrato compartilhado.

suspend fun createEmbedded(activity: Activity, client: DobroDeskClient, options: JsonObject = {}): DobroDeskWidgetEmbeddedHandle

Erros

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

DobroDeskWidgetEmbeddedHandle

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

view: DobroDeskWidgetView; isOpen: Boolean; setVisible(Boolean); close(): Unit

voiceFactory

Instala ou remove a fábrica de voz nativa opcional usada pelas apresentações do widget.

DobroDeskWidgetBridgePresenter.installVoiceFactory(factory); uninstallVoiceFactory()

Erros

• unsupported
• invalid-config

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(), stop(), setMuted(), bargeIn(), dispose()

Erros

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

push

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.

iOS: DobroDeskPush product; 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 | ATTACHMENT_POLICY_FAILED | ATTACHMENT_RATE_LIMITED | ACTION_IDENTITY_REQUIRED | COMMERCE_IDENTITY_REQUIRED | COMMERCE_UNAVAILABLE | SHOPIFY_RECONNECT_REQUIRED | SHOPIFY_RATE_LIMITED | NOT_FOUND