iOS SDK: API reference

apiOrigin

Required

The API origin is HTTPS in production. Native clients allow localhost HTTP for development.

URL

integrationId

Required

The public integration identifier copied from the DobroDesk widget channel.

String

accountScope

Required

A stable customer or account key that isolates durable session and outbox state.

String

locale

Default: en

The widget locale used for content. Web defaults to auto; native widget bundles currently support en, uk, de and es.

String = "en"

credentialProvider

Required

A host backend function that returns a short-lived signed customer JWT. Keep its signing secret out of the app.

() async throws -> String

turnstileToken

An optional Turnstile token for integrations that require it.

String?

pollInterval

Default: 1

A bounded interval used while polling for an asynchronous assistant response.

TimeInterval = 1

DobroDeskClient

Creates the client and validates the integration configuration.

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

Errors

• invalid-config
• outbox-corrupt

events

Subscribes to canonical SDK events. Release the listener with the subscription, cancellation callback or stream subscription returned by that platform.

events() -> AsyncStream<DobroDeskEvent>

state getters

Returns the current widget state without subscribing.

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

loadWidgetAppearance

Loads the validated appearance or content bundle for the native widget.

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

Errors

• network
• http
• session-expired

loadWidgetContent

Loads the validated appearance or content bundle for the native widget.

loadWidgetContent() async throws -> DobroDeskWidgetContentSnapshot

Errors

• network
• http
• field-invalid

startSession

Starts one conversation with an idempotent initial message.

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

Errors

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

resumeSession

Restores account-scoped state or resumes a server session when one exists.

resumeSession() async throws -> DobroDeskSession?

Errors

• network
• session-expired
• outbox-corrupt

restoreSession

Restores a supplied accepted session proof and loads its snapshot.

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

Errors

• session-expired
• network

refresh

Loads the current conversation snapshot.

refresh() async throws -> DobroDeskSnapshot

Errors

• network
• session-expired
• message-rejected

waitForAssistant

Polls with bounded timing until assistant work completes or the wait expires.

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

Errors

• realtime-unavailable
• network
• session-expired

sendMessage

Sends a message and returns its accepted, queued or review status.

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

Errors

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

attachments

Sends a message and returns its accepted, queued or review status.

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

Errors

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

performOperation / performNativeOperation

Exposes typed form, client-tool, attachment and commerce operations over the native engine.

performOperation(requestJson: String) async throws -> String

Errors

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

NativeOperation

Returns decoded JSON from the native operation bridge. Treat validation, transport, expiry and server rejection as explicit outcomes.

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"

Errors

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

submit-form request

Submits bounded values for a server-provided conversation form. The request identifier and values are validated before the signed native request is sent.

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

Returns

JsonValue

Errors

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

request-client-tool request

Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.

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

Returns

JsonValue

Errors

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

complete-client-tool request

Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.

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

Returns

JsonValue

Errors

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

client-tool-status request

Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.

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

Returns

JsonValue

Errors

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

procedure-action request

Advances a server-provided procedure action with an idempotency key and the expected workflow revision.

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

Returns

JsonValue

Errors

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

attachment-intents request

Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.

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

Returns

JsonValue

Errors

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

upload-attachment request

Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.

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

Returns

JsonValue

Errors

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

list-orders request

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

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

Returns

JsonValue

Errors

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

order-detail request

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

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

Returns

JsonValue

Errors

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

create-commerce-proposal request

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

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

Returns

JsonValue

Errors

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

confirm-commerce-proposal request

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

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

Returns

JsonValue

Errors

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

commerce-proposal request

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

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

Returns

JsonValue

Errors

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

NativeOperationBridgeResult

Returns decoded JSON from the native operation bridge. Treat validation, transport, expiry and server rejection as explicit outcomes.

{ valueJson: string }

Returns

JsonValue

Errors

• http

HostActionResult

Allowlisted application callbacks for guided widget actions. They do not authenticate network requests.

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

ClientToolRequest

Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.

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

ClientToolResult

Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.

{ callId: string; output: ClientToolPayload }

ProcedureActionInput

Advances a server-provided procedure action with an idempotency key and the expected workflow revision.

{ 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

Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.

{ clientId: string; fileName: string; mimeType: string; sizeBytes: number; kind: "image" | "video" | "pdf" | "text" }

AttachmentUploadIntent

Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.

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

CommerceOrderQuery

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

{ cursor?: string; store?: string }

CommerceProposalInput

Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.

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

flushOutbox

Replays pending mutations with the original body and idempotency key.

flushOutbox() async throws -> [DobroDeskAcceptedMessage]

Errors

• network
• outbox-corrupt
• session-expired

resetSession

Clears the account-scoped session, snapshot and pending mutations.

resetSession() async throws

Errors

• request-in-progress
• outbox-corrupt

WidgetExperience

The shared appearance-v2 object: colors, typography, layout and shadow within documented bounds.

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

Errors

• field-invalid
• unsupported

reducedMotion

Use the system setting by default. Native hosts also respect accessibility, low-power and thermal policies.

system | always

DobroDeskWidgetLocaleCatalog.copy(for:)

Loads a bundled native map for the main widget copy. The catalog validates that shared copy contract and currently includes en, uk, de and es; derived procedure, role and validation labels are separate.

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

Errors

• field-invalid

DobroDeskWidgetCopy.init(values:)

Builds or reads the validated shared widget copy. Unknown, missing, empty or overlong values are rejected before rendering.

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

Errors

• field-invalid

DobroDeskWidgetCopy.requiredKeys

Builds or reads the validated shared widget copy. Unknown, missing, empty or overlong values are rejected before rendering.

Set<String>

DobroDeskWidgetExperience.decodeAndResolve

Decodes and resolves the shared design contract with platform overrides, copy overrides and the host's system reduced-motion state.

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

Returns

DobroDeskWidgetExperience

Errors

• field-invalid
• unsupported

DobroDeskWidgetExperience.resolve

Decodes and resolves the shared design contract with platform overrides, copy overrides and the host's system reduced-motion state.

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

Returns

DobroDeskWidgetExperience

Errors

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Presents the native widget using the shared widget experience.

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

Errors

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

DobroDeskWidgetViewController

Presents the native widget using the shared widget experience.

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

close

Closes the current native presentation or releases a mounted host.

DobroDeskWidgetBridgePresenter.close(animated: Bool = true)

DobroDeskWidgetBridgePresenter.embed

Presents the native widget using the shared widget experience.

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

Errors

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

setEmbeddedVisible

Native navigation and web launcher or panel presentation options.

setEmbeddedVisible(_ visible: Bool)

voiceFactory

Installs or removes the optional native voice factory used by widget presentations.

DobroDeskWidgetBridgePresenter.installVoiceFactory(_ factory: DobroDeskWidgetVoiceFactory); uninstallVoiceFactory()

Errors

• unsupported
• invalid-config

voice lifecycle

Controls an optional host-installed voice capability: start, stop, mute, barge-in and disposal. The browser widget may render voice UI, but this SDK API controls only a host-provided voice bridge.

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

Errors

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

push

Describes the separate opt-in native push artifact and host registration flow. Framework wrappers do not export a JavaScript or Dart push client; use the iOS or Android native module.

iOS: DobroDeskPush product

SdkErrorCode

Handle stable machine-readable codes and keep server diagnostics out of customer UI.

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