Android SDK: API-Referenz

apiOrigin

Erforderlich

Der API-Origin ist in der Produktion HTTPS. Native Clients erlauben HTTP auf localhost für die Entwicklung.

URL | String

integrationId

Erforderlich

Die öffentliche Integrationskennung aus dem DobroDesk-Widget-Kanal.

String

accountScope

Erforderlich

Ein stabiler Kunden- oder Kontoschlüssel, der dauerhaften Sitzungs- und Outbox-Zustand isoliert.

String

locale

Standardwert: en

Widget-Locale für Inhalte. Web verwendet standardmäßig auto; native Widget-Bundles unterstützen derzeit en, uk, de und es.

String = "en"

credentialProvider

Erforderlich

Eine Backend-Funktion für ein kurzlebiges signiertes Kunden-JWT. Das Signiergeheimnis bleibt außerhalb der App.

() async throws -> String | suspend () -> String

turnstileToken

Ein optionales Turnstile-Token für Integrationen, die es benötigen.

String?

pollInterval

Standardwert: 1s

Ein begrenztes Intervall zum Abfragen einer asynchronen Antwort des Assistenten.

TimeInterval | Duration = 1s

DobroDeskClient

Erstellt den Client und prüft die Integrationskonfiguration.

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

Fehler

• invalid-config
• outbox-corrupt

subscribe

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

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

state getters

Liefert den aktuellen Widget-Status ohne Abonnement.

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

loadWidgetAppearance

Lädt das validierte Appearance- oder Content-Bundle für das native Widget.

loadWidgetAppearance(): JsonObject suspend

Fehler

• network
• http
• session-expired

loadWidgetContent

Lädt das validierte Appearance- oder Content-Bundle für das native Widget.

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

Fehler

• network
• http
• field-invalid

startSession

Startet eine Unterhaltung mit idempotenter erster Nachricht.

startSession(input: SessionStartInput): DobroDeskSession suspend

Fehler

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

resumeSession

Stellt den Kontostatus oder eine Serversitzung wieder her.

resumeSession(): DobroDeskSession? suspend

Fehler

• network
• session-expired
• outbox-corrupt

restoreSession

Stellt einen akzeptierten Sitzungsnachweis wieder her und lädt dessen Snapshot.

restoreSession(restored: DobroDeskSession): ConversationSnapshot suspend

Fehler

• session-expired
• network

refresh

Lädt den aktuellen Unterhaltungsverlauf.

refresh(): ConversationSnapshot suspend

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: Duration = Duration.ofSeconds(30), afterMessageCount: Int? = null): ConversationSnapshot suspend

Fehler

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

sendMessage

Sendet eine Nachricht und liefert ihren Lieferstatus.

sendMessage(input: MessageInput): AcceptedMessage suspend

Fehler

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

attachments

Sendet eine Nachricht und liefert ihren Lieferstatus.

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

Fehler

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

performOperation / performNativeOperation

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

performNativeOperation(requestJson: String, resolveFile: suspend (String, String) -> DobroDeskAttachmentSource): String

Fehler

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

NativeOperation

Liefert dekodiertes JSON aus der nativen Operationsbrücke. Behandeln Sie Validierungs-, Transport-, Ablauf- und Serverablehnungen ausdrücklich.

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"

Fehler

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

submit-form request

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

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

Rückgabewert

JsonValue

Fehler

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

request-client-tool request

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

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

Rückgabewert

JsonValue

Fehler

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

complete-client-tool request

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

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

Rückgabewert

JsonValue

Fehler

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

client-tool-status request

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

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

Rückgabewert

JsonValue

Fehler

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

procedure-action request

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

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

Rückgabewert

JsonValue

Fehler

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

attachment-intents request

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

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

Rückgabewert

JsonValue

Fehler

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

upload-attachment request

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

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

Rückgabewert

JsonValue

Fehler

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

list-orders request

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

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

Rückgabewert

JsonValue

Fehler

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

order-detail request

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

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

Rückgabewert

JsonValue

Fehler

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

create-commerce-proposal request

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

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

Rückgabewert

JsonValue

Fehler

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

confirm-commerce-proposal request

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

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

Rückgabewert

JsonValue

Fehler

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

commerce-proposal request

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

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

Rückgabewert

JsonValue

Fehler

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

NativeOperationBridgeResult

Liefert dekodiertes JSON aus der nativen Operationsbrücke. Behandeln Sie Validierungs-, Transport-, Ablauf- und Serverablehnungen ausdrücklich.

{ valueJson: string }

Rückgabewert

JsonValue

Fehler

• http

HostActionResult

Freigegebene Anwendungs-Callbacks für geführte Widget-Aktionen. Sie authentifizieren keine Netzwerkanfragen.

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

ClientToolRequest

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: ClientToolPayload }

ClientToolResult

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: ClientToolPayload }

ProcedureActionInput

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

{ 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

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: number; kind: "image" | "video" | "pdf" | "text" }

AttachmentUploadIntent

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 }

CommerceOrderQuery

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

{ cursor?: string; store?: string }

CommerceProposalInput

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

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

requestAttachmentIntents

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

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

Fehler

• attachment_policy_failed
• session-expired
• network
• http

uploadAttachment

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

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

Fehler

• attachment_policy_failed
• session-expired
• network
• http

downloadAttachment

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

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

Fehler

• attachment_policy_failed
• session-expired
• network
• http

canDownloadAttachment

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

canDownloadAttachment(downloadUrl: String): Boolean

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.

requestClientTool(requestInput: DobroDeskClientToolRequest) suspend -> DobroDeskClientToolResponse

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.

completeClientTool(result: DobroDeskClientToolResult) suspend -> DobroDeskClientToolResponse

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.

clientToolStatus(callId: String) suspend -> DobroDeskClientToolResponse

Fehler

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

submitConversationForm

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

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

Fehler

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

performProcedureAction

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

performProcedureAction(action: DobroDeskProcedureActionRequest) suspend -> Unit

Fehler

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

loadCommerceOrders

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

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

Fehler

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

loadCommerceOrderDetail

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

loadCommerceOrderDetail(orderReference: String) suspend -> JsonElement?

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.

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

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.

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

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.

commerceProposal(proposalId: String) suspend -> JsonElement?

Fehler

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

flushOutbox

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

flushOutbox(): List<AcceptedMessage> suspend

Fehler

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() suspend

Fehler

• request-in-progress
• outbox-corrupt

WidgetExperience

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

reducedMotion

Standardmäßig folgt die App der Systemeinstellung sowie den nativen Energiespar- und Thermalrichtlinien.

system | always

WidgetLocaleCopies.forLocale

Lädt eine integrierte native Karte für die Haupttexte des Widgets. Der Katalog prüft den gemeinsamen Textvertrag und enthält derzeit en, uk, de und es; abgeleitete Verfahrens-, Rollen- und Validierungstexte sind getrennt.

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

Fehler

• field-invalid

WidgetCopy(values)

Erstellt oder liest die validierten gemeinsamen Widget-Texte. Unbekannte, fehlende, leere oder zu lange Werte werden vor der Darstellung abgelehnt.

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

Fehler

• field-invalid

WidgetCopy.requiredKeys

Erstellt oder liest die validierten gemeinsamen Widget-Texte. Unbekannte, fehlende, leere oder zu lange Werte werden vor der Darstellung abgelehnt.

Set<String>

WidgetCopy.text

Erstellt oder liest die validierten gemeinsamen Widget-Texte. Unbekannte, fehlende, leere oder zu lange Werte werden vor der Darstellung abgelehnt.

WidgetCopy.text(key: String): String

Fehler

• field-invalid

WidgetExperience.decodeAndResolve

Dekodiert und löst den gemeinsamen Designvertrag mit Plattform- und Textüberschreibungen sowie dem Systemstatus für weniger Bewegung des Hosts auf.

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

Rückgabewert

WidgetExperience

Fehler

• field-invalid
• unsupported

WidgetExperience.resolve

Dekodiert und löst den gemeinsamen Designvertrag mit Plattform- und Textüberschreibungen sowie dem Systemstatus für weniger Bewegung des Hosts auf.

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

Rückgabewert

WidgetExperience

Fehler

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

Fehler

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

close / detach

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

close(): Unit; detach(): Unit

DobroDeskWidgetBridgePresenter.createEmbedded

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

Fehler

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

DobroDeskWidgetEmbeddedHandle

Optionen für native Navigation sowie die Darstellung des Web-Launchers oder Panels.

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

voiceFactory

Installiert oder entfernt die optionale native Sprachfabrik für Widget-Darstellungen.

DobroDeskWidgetBridgePresenter.installVoiceFactory(factory); uninstallVoiceFactory()

Fehler

• unsupported
• invalid-config

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(), stop(), setMuted(), bargeIn(), dispose()

Fehler

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

push

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.

iOS: DobroDeskPush product; Android: com.dobrodesk:dobrodesk-push:<version>

SdkErrorCode

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

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