iOS 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

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

turnstileToken

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

String?

pollInterval

Valor padrão: 1

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

TimeInterval = 1

DobroDeskClient

Cria o cliente e valida a configuração.

init(configuration: DobroDeskConfiguration, outbox: any DobroDeskOutboxStore = ..., pendingSessionStarts: any DobroDeskPendingSessionStartStore = ..., sessionStore: any DobroDeskSessionStore = ..., pendingAttachmentSends: any DobroDeskPendingAttachmentStore = ..., pendingAttachmentOperations: any DobroDeskPendingAttachmentOperationStore = ..., transport: any DobroDeskHTTPTransport = ...)

Erros

• invalid-config
• outbox-corrupt

events

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.

events() -> AsyncStream<DobroDeskEvent>

state getters

Retorna o estado atual do widget sem assinar eventos.

currentSession(), currentConfiguration(), currentWidgetVoiceSettings(), currentWidgetWorkspacePublicName(), currentWidgetChannels(), currentWidgetNavigation(), currentWidgetAvailability(), currentSnapshot(), currentWidgetContent(), currentLoadingState(), currentCustomerMessageId(), shouldWaitForAssistant()

loadWidgetAppearance

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

loadWidgetAppearance() async throws -> [String: JSONValue]

Erros

• network
• http
• session-expired

loadWidgetContent

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

loadWidgetContent() async throws -> DobroDeskWidgetContentSnapshot

Erros

• network
• http
• field-invalid

startSession

Inicia uma conversa com uma primeira mensagem idempotente.

startSession(_ input: DobroDeskSessionStartInput) async throws -> DobroDeskSession

Erros

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

resumeSession

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

resumeSession() async throws -> DobroDeskSession?

Erros

• network
• session-expired
• outbox-corrupt

restoreSession

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

restoreSession(_ restored: DobroDeskSession) async throws -> DobroDeskSnapshot

Erros

• session-expired
• network

refresh

Carrega o estado atual da conversa.

refresh() async throws -> DobroDeskSnapshot

Erros

• network
• session-expired
• message-rejected

waitForAssistant

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

waitForAssistant(timeout: TimeInterval = 30, afterMessageCount: Int? = nil) async throws -> DobroDeskSnapshot

Erros

• realtime-unavailable
• network
• session-expired

sendMessage

Envia uma mensagem e retorna o status de entrega.

sendMessage(_ input: DobroDeskMessageInput) async throws -> DobroDeskAcceptedMessage

Erros

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

attachments

Envia uma mensagem e retorna o status de entrega.

startSession(_:attachments:), sendMessage(_:attachments:)

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.

performOperation(requestJson: String) async throws -> 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 }[] } }

flushOutbox

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

flushOutbox() async throws -> [DobroDeskAcceptedMessage]

Erros

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() async throws

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

DobroDeskWidgetLocaleCatalog.copy(for:)

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.

DobroDeskWidgetLocaleCatalog.copy(for locale: String) throws -> [String: String]

Erros

• field-invalid

DobroDeskWidgetCopy.init(values:)

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

DobroDeskWidgetCopy(values: [String: String]) throws -> DobroDeskWidgetCopy

Erros

• field-invalid

DobroDeskWidgetCopy.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>

DobroDeskWidgetExperience.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.

decodeAndResolve(_ data: Data, platform: DobroDeskWidgetPlatform, osReducedMotion: Bool, localeCopy: [String: String], decoder: JSONDecoder = JSONDecoder()) throws -> DobroDeskWidgetExperience

Retorna

DobroDeskWidgetExperience

Erros

• field-invalid
• unsupported

DobroDeskWidgetExperience.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.

resolve(_ input: DobroDeskWidgetExperienceInput, platform: DobroDeskWidgetPlatform, osReducedMotion: Bool, localeCopy: [String: String]) throws -> DobroDeskWidgetExperience

Retorna

DobroDeskWidgetExperience

Erros

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Apresenta o widget nativo com o contrato compartilhado.

present(client: DobroDeskClient, options: NSDictionary, from: UIViewController) async throws

Erros

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

DobroDeskWidgetViewController

Apresenta o widget nativo com o contrato compartilhado.

init(client: DobroDeskClient, experience: DobroDeskWidgetExperience, ...)

close

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

DobroDeskWidgetBridgePresenter.close(animated: Bool = true)

DobroDeskWidgetBridgePresenter.embed

Apresenta o widget nativo com o contrato compartilhado.

embed(client: DobroDeskClient, options: NSDictionary, in container: UIView, parent: UIViewController) async throws

Erros

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

setEmbeddedVisible

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

setEmbeddedVisible(_ visible: Bool)

voiceFactory

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

DobroDeskWidgetBridgePresenter.installVoiceFactory(_ factory: DobroDeskWidgetVoiceFactory); 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.

DobroDeskVoiceClient.start(), stop(), setMuted(), bargeIn(), pauseForBackground(), resumeAfterForeground(), handleAudioInterruption(ended:shouldResume:), handleRouteChange()

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

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