Android SDK: API reference

apiOrigin

Required

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

URL | String

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 | suspend () -> String

turnstileToken

An optional Turnstile token for integrations that require it.

String?

pollInterval

Default: 1s

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

TimeInterval | Duration = 1s

DobroDeskClient

Creates the client and validates the integration configuration.

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

Errors

• invalid-config
• outbox-corrupt

subscribe

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

subscribe(listener: (SdkEvent) -> Unit): () -> Unit

state getters

Returns the current widget state without subscribing.

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

loadWidgetAppearance

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

loadWidgetAppearance(): JsonObject suspend

Errors

• network
• http
• session-expired

loadWidgetContent

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

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

Errors

• network
• http
• field-invalid

startSession

Starts one conversation with an idempotent initial message.

startSession(input: SessionStartInput): DobroDeskSession suspend

Errors

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

resumeSession

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

resumeSession(): DobroDeskSession? suspend

Errors

• network
• session-expired
• outbox-corrupt

restoreSession

Restores a supplied accepted session proof and loads its snapshot.

restoreSession(restored: DobroDeskSession): ConversationSnapshot suspend

Errors

• session-expired
• network

refresh

Loads the current conversation snapshot.

refresh(): ConversationSnapshot suspend

Errors

• network
• session-expired
• message-rejected

waitForAssistant

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

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

Errors

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

sendMessage

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

sendMessage(input: MessageInput): AcceptedMessage suspend

Errors

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

attachments

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

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

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.

performNativeOperation(requestJson: String, resolveFile: suspend (String, String) -> DobroDeskAttachmentSource): 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 }[] } }

requestAttachmentIntents

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

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

Errors

• attachment_policy_failed
• session-expired
• network
• http

uploadAttachment

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

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

Errors

• attachment_policy_failed
• session-expired
• network
• http

downloadAttachment

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

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

Errors

• attachment_policy_failed
• session-expired
• network
• http

canDownloadAttachment

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

canDownloadAttachment(downloadUrl: String): Boolean

requestClientTool

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

requestClientTool(requestInput: DobroDeskClientToolRequest) suspend -> DobroDeskClientToolResponse

Errors

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

completeClientTool

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

completeClientTool(result: DobroDeskClientToolResult) suspend -> DobroDeskClientToolResponse

Errors

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

clientToolStatus

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

clientToolStatus(callId: String) suspend -> DobroDeskClientToolResponse

Errors

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

submitConversationForm

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

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

Errors

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

performProcedureAction

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

performProcedureAction(action: DobroDeskProcedureActionRequest) suspend -> Unit

Errors

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

loadCommerceOrders

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

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

Errors

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

loadCommerceOrderDetail

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

loadCommerceOrderDetail(orderReference: String) suspend -> JsonElement?

Errors

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

createCommerceProposal

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

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

Errors

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

confirmCommerceProposal

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

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

Errors

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

commerceProposal

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

commerceProposal(proposalId: String) suspend -> JsonElement?

Errors

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

flushOutbox

Replays pending mutations with the original body and idempotency key.

flushOutbox(): List<AcceptedMessage> suspend

Errors

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() suspend

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

WidgetLocaleCopies.forLocale

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.

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

Errors

• field-invalid

WidgetCopy(values)

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

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

Errors

• field-invalid

WidgetCopy.requiredKeys

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

Set<String>

WidgetCopy.text

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

WidgetCopy.text(key: String): String

Errors

• field-invalid

WidgetExperience.decodeAndResolve

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

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

Returns

WidgetExperience

Errors

• field-invalid
• unsupported

WidgetExperience.resolve

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

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

Returns

WidgetExperience

Errors

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Presents the native widget using the shared widget experience.

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

Errors

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

close / detach

Closes the current native presentation or releases a mounted host.

close(): Unit; detach(): Unit

DobroDeskWidgetBridgePresenter.createEmbedded

Presents the native widget using the shared widget experience.

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

Errors

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

DobroDeskWidgetEmbeddedHandle

Native navigation and web launcher or panel presentation options.

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

voiceFactory

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

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

start(), stop(), setMuted(), bargeIn(), dispose()

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; Android: com.dobrodesk:dobrodesk-push:<version>

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 | ATTACHMENT_POLICY_FAILED | ATTACHMENT_RATE_LIMITED | ACTION_IDENTITY_REQUIRED | COMMERCE_IDENTITY_REQUIRED | COMMERCE_UNAVAILABLE | SHOPIFY_RECONNECT_REQUIRED | SHOPIFY_RATE_LIMITED | NOT_FOUND