Flutter SDK: API-Referenz

DobroDeskFlutterClient

Erforderlich

Die Framework-Konfiguration liefert App-Identität und Kontobereich und bezieht über den Credential-Provider des Hosts ein neues kurzlebiges Authorization-Token. Token- und Ergebnisformen entsprechen der angezeigten Plattform-Signatur.

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 })

Fehler

• invalid-config

DobroDeskFlutterClient

Erstellt den Client und prüft die Integrationskonfiguration.

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

startSession

Startet eine Unterhaltung mit idempotenter erster Nachricht.

startSession(String message, { prefill?, idempotencyKey?, metadata?, timeZone?, turnstileToken?, startedAt? }): Future<DobroDeskSession>

Fehler

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

resumeSession

Stellt den Kontostatus oder eine Serversitzung wieder her.

resumeSession(): Future<DobroDeskSession?>

Fehler

• network
• session-expired
• outbox-corrupt

refresh

Lädt den aktuellen Unterhaltungsverlauf.

refresh(): Future<DobroDeskSnapshot>

Fehler

• network
• session-expired
• message-rejected

waitForAssistant

Fragt mit begrenztem Timing ab, bis die Arbeit des Assistenten abgeschlossen ist oder die Wartezeit endet.

waitForAssistant({ timeout?, afterMessageCount? }): Future<DobroDeskSnapshot>

Fehler

• realtime-unavailable
• network
• session-expired

sendMessage

Sendet eine Nachricht und liefert ihren Lieferstatus.

sendMessage(String text, { String? idempotencyKey }): Future<DobroDeskAcceptedMessage>

Fehler

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

flushOutbox

Wiederholt ausstehende Mutationen mit unverändertem Inhalt und Schlüssel.

flushOutbox(): Future<List<DobroDeskAcceptedMessage>>

Fehler

• network
• outbox-corrupt
• session-expired

resetSession

Löscht die kontobezogene Sitzung, den Snapshot und ausstehende Mutationen.

resetSession(): Future<void>

Fehler

• request-in-progress
• outbox-corrupt

setAuthorizationToken

Übergibt einem nativen Bridge das aktuelle kurzlebige Token.

setAuthorizationToken(String token): Future<void>

logout

Beendet die Kundensitzung und optionale Funktionen.

logout(): Future<void>

Fehler

• outbox-corrupt

presentWidget

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

Fehler

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

closeWidget

Schließt die aktuelle native Darstellung oder gibt einen gemounteten Host frei.

closeWidget(): Future<void>

events

Abonniert kanonische SDK-Ereignisse. Zum Freigeben des Listeners verwenden Sie die von der Plattform gelieferte Subscription, den Abbruch-Callback oder die Stream-Subscription.

events: Stream<DobroDeskEvent>

operations

Stellt typisierte Formular-, Client-Tool-, Anhang- und Commerce-Operationen über die native Engine bereit.

operations: DobroDeskOperations

submitForm

Übermittelt begrenzte Werte für ein vom Server bereitgestelltes Gesprächsformular. Anfragekennung und Werte werden vor der signierten nativen Anfrage geprüft.

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

Rückgabewert

Future<Object?>

Fehler

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

requestClientTool

Fordert ein freigegebenes Client-Tool an, bestätigt sein Ergebnis oder liest seinen Status. Tool-Payloads sind flach, begrenzt und lehnen sensible Feldnamen ab.

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

Rückgabewert

Future<Object?>

Fehler

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

completeClientTool

Fordert ein freigegebenes Client-Tool an, bestätigt sein Ergebnis oder liest seinen Status. Tool-Payloads sind flach, begrenzt und lehnen sensible Feldnamen ab.

operations.completeClientTool(input: DobroDeskClientToolResult): Future<Object?>

Rückgabewert

Future<Object?>

Fehler

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

clientToolStatus

Fordert ein freigegebenes Client-Tool an, bestätigt sein Ergebnis oder liest seinen Status. Tool-Payloads sind flach, begrenzt und lehnen sensible Feldnamen ab.

operations.clientToolStatus(String callId): Future<Object?>

Rückgabewert

Future<Object?>

Fehler

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

procedureAction

Führt eine serverseitige Verfahrensaktion mit Idempotenzschlüssel und erwarteter Workflow-Version fort.

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

Rückgabewert

Future<Object?>

Fehler

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

attachmentIntents

Erstellt Upload-Intents und lädt ausgewählte lokale Dateien innerhalb der SDK-Grenzen für Größe, Typ, URI und Richtlinie hoch.

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

Rückgabewert

Future<Object?>

Fehler

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

uploadAttachment

Erstellt Upload-Intents und lädt ausgewählte lokale Dateien innerhalb der SDK-Grenzen für Größe, Typ, URI und Richtlinie hoch.

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

Rückgabewert

Future<Object?>

Fehler

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

listOrders

Liest Bestelldaten und erstellt, bestätigt oder liest einen begrenzten Shopify-Vorschlag zur Bestellstornierung.

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

Rückgabewert

Future<Object?>

Fehler

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

orderDetail

Liest Bestelldaten und erstellt, bestätigt oder liest einen begrenzten Shopify-Vorschlag zur Bestellstornierung.

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

Rückgabewert

Future<Object?>

Fehler

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

createCommerceProposal

Liest Bestelldaten und erstellt, bestätigt oder liest einen begrenzten Shopify-Vorschlag zur Bestellstornierung.

operations.createCommerceProposal({required String storeReference, required String orderReference, required String idempotencyKey}): Future<Object?>

Rückgabewert

Future<Object?>

Fehler

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

confirmCommerceProposal

Liest Bestelldaten und erstellt, bestätigt oder liest einen begrenzten Shopify-Vorschlag zur Bestellstornierung.

operations.confirmCommerceProposal(String proposalId, String idempotencyKey): Future<Object?>

Rückgabewert

Future<Object?>

Fehler

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

commerceProposal

Liest Bestelldaten und erstellt, bestätigt oder liest einen begrenzten Shopify-Vorschlag zur Bestellstornierung.

operations.commerceProposal(String proposalId): Future<Object?>

Rückgabewert

Future<Object?>

Fehler

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

DobroDeskClientToolRequest

Fordert ein freigegebenes Client-Tool an, bestätigt sein Ergebnis oder liest seinen Status. Tool-Payloads sind flach, begrenzt und lehnen sensible Feldnamen ab.

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

DobroDeskClientToolResult

Fordert ein freigegebenes Client-Tool an, bestätigt sein Ergebnis oder liest seinen Status. Tool-Payloads sind flach, begrenzt und lehnen sensible Feldnamen ab.

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

DobroDeskAttachmentDescriptor

Erstellt Upload-Intents und lädt ausgewählte lokale Dateien innerhalb der SDK-Grenzen für Größe, Typ, URI und Richtlinie hoch.

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

DobroDeskUploadIntent

Erstellt Upload-Intents und lädt ausgewählte lokale Dateien innerhalb der SDK-Grenzen für Größe, Typ, URI und Richtlinie hoch.

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

DobroDeskLoadingState

Der gemeinsame Ladezustand ist idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting oder flushing-outbox.

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

DobroDeskEvent

Native und Wrapper-Ereignisse verwenden das gemeinsame Envelope für Laden, Sitzung, Snapshot, akzeptierte Nachricht, Fehler und gelöschte Sitzung.

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

dispose

Stoppt die Arbeit optionaler Funktionen und gibt Host-Ressourcen frei.

dispose(): Future<void>

WidgetExperience (JSON schema)

Das gemeinsame appearance-v2-Objekt mit Farben, Typografie, Layout und Schatten innerhalb der dokumentierten Grenzen.

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

Fehler

• field-invalid
• unsupported

DobroDeskWidgetView

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

beginInlineWidget

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

beginInlineWidget(NativeWidgetOptions options, String ownerId): Future<void>

Fehler

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

mountInlineWidget

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

mountInlineWidget(String ownerId): Future<void>

Fehler

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

disposeInlineWidget

Schließt die aktuelle native Darstellung oder gibt einen gemounteten Host frei.

disposeInlineWidget(String ownerId): Future<void>

NativeOperation (wrapper bridge)

Stellt typisierte Formular-, Client-Tool-, Anhang- und Commerce-Operationen über die native Engine bereit.

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-Brücken kodieren den Abschluss einer Host-Aktion über eine lokale native Präsentationsbrücke. Er wird nicht als HTTP-Operation über den direkten nativen Client gesendet.

{ operation: "complete-host-action"; requestId: string; actionId: string; result: HostActionResult }

Rückgabewert

JsonValue

Fehler

• field-invalid
• session-expired
• unsupported

attachVoice

Verbindet die separat installierte, vom Host verwaltete Sprachfunktion.

attachVoice(DobroDeskVoicePort port): Future<DobroDeskVoiceFacade>

Fehler

• unsupported
• invalid-config

voice

Steuert eine optionale, vom Host installierte Sprachfunktion: Start, Stopp, Stummschaltung, Barge-in und Freigabe. Das Browser-Widget kann eine Sprachoberfläche anzeigen, aber diese SDK-API steuert nur eine vom Host bereitgestellte Sprachbrücke.

voice: DobroDeskVoiceFacade?

voice lifecycle

Steuert eine optionale, vom Host installierte Sprachfunktion: Start, Stopp, Stummschaltung, Barge-in und Freigabe. Das Browser-Widget kann eine Sprachoberfläche anzeigen, aber diese SDK-API steuert nur eine vom Host bereitgestellte Sprachbrücke.

start(): Future<void>; stop(): Future<void>; setMuted(bool muted): Future<void>; bargeIn(): Future<void>; dispose(): Future<void>

Fehler

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

push module (native only)

Beschreibt das optionale native Push-Artefakt und die Host-Registrierung. Framework-Wrapper exportieren keinen JavaScript- oder Dart-Push-Client; verwenden Sie das native iOS- oder Android-Modul.

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

DobroDeskException

Behandeln Sie stabile maschinenlesbare Codes und halten Sie Serverdiagnosen aus der Kundenoberfläche fern.

DobroDeskException(String code, String message, { int? status, int? retryAfterSeconds, String? fieldId, String? requestId }); code: String

Fehler

• 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