Skip to main content
Get started
DocumentationFlutter
Version 0.2.0Flutter 3.22.3 and Dart 3.4 or later

Flutter SDK: API reference

Flutter: A typed bridge to the shared native iOS and Android engines for the selected mobile framework.

On this page

Configuration

DobroDeskFlutterClient

Required

Framework configuration supplies app identity and account scope and obtains a fresh short-lived authorization token from the host credential provider. Token and result shapes follow the displayed platform signature.

DobroDeskFlutterClient
DobroDeskFlutterClient({ required String integrationId, required String apiOrigin, required String accountScope, String? authorizationToken, Future<String> Function()? credentialProvider, String locale = 'en', Duration pollInterval = const Duration(seconds: 1), Map<String, Object?>? context, Map<String, DobroDeskHostActionHandler>? hostActions, MethodChannel? methodChannel, EventChannel? eventChannel })
Errors
  • invalid-config

Lifecycle and conversation

DobroDeskFlutterClient

Creates the client and validates the integration configuration.

DobroDeskFlutterClient
new DobroDeskFlutterClient({ integrationId, apiOrigin, accountScope, authorizationToken?, credentialProvider? })

startSession

Starts one conversation with an idempotent initial message.

startSession
startSession(String message, { prefill?, idempotencyKey?, metadata?, timeZone?, turnstileToken?, startedAt? }): Future<DobroDeskSession>
Errors
  • network
  • field-invalid
  • idempotency-conflict
  • outbox-corrupt

resumeSession

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

resumeSession
resumeSession(): Future<DobroDeskSession?>
Errors
  • network
  • session-expired
  • outbox-corrupt

refresh

Loads the current conversation snapshot.

refresh
refresh(): Future<DobroDeskSnapshot>
Errors
  • network
  • session-expired
  • message-rejected

waitForAssistant

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

waitForAssistant
waitForAssistant({ timeout?, afterMessageCount? }): Future<DobroDeskSnapshot>
Errors
  • realtime-unavailable
  • network
  • session-expired

sendMessage

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

sendMessage
sendMessage(String text, { String? idempotencyKey }): Future<DobroDeskAcceptedMessage>
Errors
  • network
  • idempotency-conflict
  • conversation-stale
  • rate-limited
  • message-rejected

flushOutbox

Replays pending mutations with the original body and idempotency key.

flushOutbox
flushOutbox(): Future<List<DobroDeskAcceptedMessage>>
Errors
  • network
  • outbox-corrupt
  • session-expired

resetSession

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

resetSession
resetSession(): Future<void>
Errors
  • request-in-progress
  • outbox-corrupt

setAuthorizationToken

Supplies the latest short-lived token to a native bridge.

setAuthorizationToken
setAuthorizationToken(String token): Future<void>

logout

Ends the active customer session and disposes optional capability state.

logout
logout(): Future<void>
Errors
  • outbox-corrupt

presentWidget

Presents the native widget using the shared widget experience.

presentWidget
presentWidget({ title?, subtitle?, appearance?, platform?, reduceMotion?, view?, articleId?, context?, hostActionIds? }): Future<void>

Parameters

titleString?
Bounded copy overrides for the shared widget copy keys.
subtitleString?
Bounded copy overrides for the shared widget copy keys.
appearanceMap<String, Object?>?
The shared appearance-v2 object: colors, typography, layout and shadow within documented bounds.
platformMap<String, Object?>?
Platform-specific safe-area, keyboard and navigation overrides within the shared design contract.
reduceMotionbool?Default: system
Use the system setting by default. Native hosts also respect accessibility, low-power and thermal policies.
viewString?
Native navigation and web launcher or panel presentation options.
articleIdString?
Bounded JSON context supplied to explicitly registered host actions.
contextMap<String, Object?>?
Bounded JSON context supplied to explicitly registered host actions.
hostActionIdsList<String>?
Allowlisted application callbacks for guided widget actions. They do not authenticate network requests.
Errors
  • invalid-config
  • request-in-progress
  • field-invalid

closeWidget

Closes the current native presentation or releases a mounted host.

closeWidget
closeWidget(): Future<void>

events

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

events
events: Stream<DobroDeskEvent>

operations

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

operations
operations: DobroDeskOperations

submitForm

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

submitForm
operations.submitForm(String requestId, Map<String, Object?> values): Future<Object?>

Parameters

requestIdStringRequired
Submits bounded values for a server-provided conversation form. The request identifier and values are validated before the signed native request is sent.
valuesMap<String, Object?>Required
Submits bounded values for a server-provided conversation form. The request identifier and values are validated before the signed native request is sent.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • message-rejected

requestClientTool

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

requestClientTool
operations.requestClientTool(input: DobroDeskClientToolRequest): Future<Object?>

Parameters

inputDobroDeskClientToolRequestRequired
Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.
Returns
Future<Object?>
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
operations.completeClientTool(input: DobroDeskClientToolResult): Future<Object?>

Parameters

inputDobroDeskClientToolResultRequired
Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.
Returns
Future<Object?>
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
operations.clientToolStatus(String callId): Future<Object?>

Parameters

callIdStringRequired
Requests an allowlisted client tool, acknowledges its result or reads its status. Tool payloads are flat, bounded and reject sensitive field names.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • not_found

procedureAction

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

procedureAction
operations.procedureAction(input: DobroDeskProcedureAction): Future<Object?>

Parameters

input.actionstart | answer | availability | select | calendar_date | back | confirm | declineRequired
Advances a server-provided procedure action with an idempotency key and the expected workflow revision.
input.valueStringRequired
Advances a server-provided procedure action with an idempotency key and the expected workflow revision.
input.idempotencyKeystring (16-128 characters)Required
Advances a server-provided procedure action with an idempotency key and the expected workflow revision.
input.procedureId / runId / expectedUpdatedAtString?
Advances a server-provided procedure action with an idempotency key and the expected workflow revision.
input.locale"en" | "uk" | "de" | "es"?
The widget locale used for content. Web defaults to auto; native widget bundles currently support en, uk, de and es.
input.stepId / parameterId / timeZoneString?
Advances a server-provided procedure action with an idempotency key and the expected workflow revision.
input.nativeCommerceUitrue?
Advances a server-provided procedure action with an idempotency key and the expected workflow revision.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • message-rejected
  • idempotency-conflict

attachmentIntents

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

attachmentIntents
operations.attachmentIntents(String messageId, List<DobroDeskAttachmentDescriptor> attachments): Future<Object?>

Parameters

messageIdStringRequired
Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.
attachmentsDobroDeskAttachmentDescriptor[] (1-5; each up to 10 MiB)Required
Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • attachment_policy_failed
  • attachment_rate_limited

uploadAttachment

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

uploadAttachment
operations.uploadAttachment(DobroDeskUploadIntent intent, String fileUri, String mimeType): Future<Object?>

Parameters

intentDobroDeskUploadIntentRequired
Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.
fileUriString (file:// or content:// URI)Required
Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.
mimeTypeStringRequired
Creates upload intents and uploads selected local files under the SDK size, type, URI and policy limits.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • attachment_policy_failed
  • attachment_rate_limited

listOrders

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

listOrders
operations.listOrders({String? cursor, String? store}): Future<Object?>

Parameters

query{String? cursor, String? store}
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • commerce_identity_required
  • commerce_unavailable
  • shopify_reconnect_required
  • shopify_rate_limited

orderDetail

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

orderDetail
operations.orderDetail(String orderRef): Future<Object?>

Parameters

orderRefStringRequired
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
Returns
Future<Object?>
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
operations.createCommerceProposal({required String storeReference, required String orderReference, required String idempotencyKey}): Future<Object?>

Parameters

storeReferenceStringRequired
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
orderReferenceStringRequired
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
idempotencyKeystring (16-128 characters)Required
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
Returns
Future<Object?>
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
operations.confirmCommerceProposal(String proposalId, String idempotencyKey): Future<Object?>

Parameters

proposalIdStringRequired
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
idempotencyKeystring (16-128 characters)Required
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
Returns
Future<Object?>
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
operations.commerceProposal(String proposalId): Future<Object?>

Parameters

proposalIdStringRequired
Reads scoped order data and creates, confirms or reads a bounded Shopify order-cancellation proposal.
Returns
Future<Object?>
Errors
  • field-invalid
  • network
  • http
  • session-expired
  • commerce_identity_required
  • commerce_unavailable
  • not_found

DobroDeskClientToolRequest

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

DobroDeskClientToolRequest
{ toolName: String; basisMessageId: String; input: Map<String, Object?> }

DobroDeskClientToolResult

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

DobroDeskClientToolResult
{ callId: String; output: Map<String, Object?> }

DobroDeskAttachmentDescriptor

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

DobroDeskAttachmentDescriptor
{ clientId: String; fileName: String; mimeType: String; sizeBytes: int; kind: String (image|video|pdf|text) }

DobroDeskUploadIntent

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

DobroDeskUploadIntent
{ clientId: String; attachmentId: String; uploadUrl: String; uploadToken: String; expiresAt: String }

DobroDeskLoadingState

The shared loading state is one of idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting or flushing-outbox.

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

DobroDeskEvent

Native and wrapper events use the shared loading, session, snapshot, accepted-message, error and session-cleared envelope.

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

dispose

Stops optional capability work and releases its host resources.

dispose
dispose(): Future<void>

Widget presentation

WidgetExperience (JSON schema)

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

WidgetExperience (JSON schema)
schemaVersion, locale, appearance, platformOverrides, presentation, reducedMotion, copy
Errors
  • field-invalid
  • unsupported

DobroDeskWidgetView

Presents the native widget using the shared widget experience.

DobroDeskWidgetView
DobroDeskWidgetView({ required DobroDeskFlutterClient client, NativeWidgetOptions options = const NativeWidgetOptions(), bool visible = true, onError?, errorBuilder? })

beginInlineWidget

Presents the native widget using the shared widget experience.

beginInlineWidget
beginInlineWidget(NativeWidgetOptions options, String ownerId): Future<void>
Errors
  • invalid-config
  • request-in-progress
  • field-invalid

mountInlineWidget

Presents the native widget using the shared widget experience.

mountInlineWidget
mountInlineWidget(String ownerId): Future<void>
Errors
  • invalid-config
  • request-in-progress
  • field-invalid

disposeInlineWidget

Closes the current native presentation or releases a mounted host.

disposeInlineWidget
disposeInlineWidget(String ownerId): Future<void>

NativeOperation (wrapper bridge)

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

NativeOperation (wrapper bridge)
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)

Framework wrappers encode host-action completion through a local native presenter bridge. It is not sent as an HTTP operation through the direct native client.

complete-host-action (local bridge)
{ operation: "complete-host-action"; requestId: string; actionId: string; result: HostActionResult }

Parameters

requestIdstringRequired
Allowlisted application callbacks for guided widget actions. They do not authenticate network requests.
actionIdstringRequired
Allowlisted application callbacks for guided widget actions. They do not authenticate network requests.
resultHostActionResultRequired
Allowlisted application callbacks for guided widget actions. They do not authenticate network requests.
Returns
JsonValue
Errors
  • field-invalid
  • session-expired
  • unsupported

Optional capabilities

attachVoice

Attaches a separately installed, host-owned voice capability.

attachVoice
attachVoice(DobroDeskVoicePort port): Future<DobroDeskVoiceFacade>
Errors
  • unsupported
  • invalid-config

voice

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.

voice
voice: DobroDeskVoiceFacade?

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.

voice lifecycle
start(): Future<void>; stop(): Future<void>; setMuted(bool muted): Future<void>; bargeIn(): Future<void>; dispose(): Future<void>
Errors
  • invalid-configuration
  • permission-denied
  • audio-unavailable
  • session-expired
  • realtime-unavailable
  • invalid-response
  • protocol-violation
  • stale-frame
  • queue-overloaded
  • cancelled
  • unsupported

push module (native only)

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.

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

Errors

DobroDeskException

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

DobroDeskException
DobroDeskException(String code, String message, { int? status, int? retryAfterSeconds, String? fieldId, String? requestId }); code: String
Errors
  • 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