iOS SDK: API-Referenz

apiOrigin

Erforderlich

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

URL

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

turnstileToken

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

String?

pollInterval

Standardwert: 1

Ein begrenztes Intervall zum Abfragen einer asynchronen Antwort des Assistenten.

TimeInterval = 1

DobroDeskClient

Erstellt den Client und prüft die Integrationskonfiguration.

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

Fehler

• invalid-config
• outbox-corrupt

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() -> AsyncStream<DobroDeskEvent>

state getters

Liefert den aktuellen Widget-Status ohne Abonnement.

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

loadWidgetAppearance

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

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

Fehler

• network
• http
• session-expired

loadWidgetContent

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

loadWidgetContent() async throws -> DobroDeskWidgetContentSnapshot

Fehler

• network
• http
• field-invalid

startSession

Startet eine Unterhaltung mit idempotenter erster Nachricht.

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

Fehler

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

resumeSession

Stellt den Kontostatus oder eine Serversitzung wieder her.

resumeSession() async throws -> DobroDeskSession?

Fehler

• network
• session-expired
• outbox-corrupt

restoreSession

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

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

Fehler

• session-expired
• network

refresh

Lädt den aktuellen Unterhaltungsverlauf.

refresh() async throws -> 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: TimeInterval = 30, afterMessageCount: Int? = nil) async throws -> DobroDeskSnapshot

Fehler

• realtime-unavailable
• network
• session-expired

sendMessage

Sendet eine Nachricht und liefert ihren Lieferstatus.

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

Fehler

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

attachments

Sendet eine Nachricht und liefert ihren Lieferstatus.

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

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.

performOperation(requestJson: String) async throws -> 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 }[] } }

flushOutbox

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

flushOutbox() async throws -> [DobroDeskAcceptedMessage]

Fehler

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() async throws

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

DobroDeskWidgetLocaleCatalog.copy(for:)

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.

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

Fehler

• field-invalid

DobroDeskWidgetCopy.init(values:)

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

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

Fehler

• field-invalid

DobroDeskWidgetCopy.requiredKeys

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

Set<String>

DobroDeskWidgetExperience.decodeAndResolve

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

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

Rückgabewert

DobroDeskWidgetExperience

Fehler

• field-invalid
• unsupported

DobroDeskWidgetExperience.resolve

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

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

Rückgabewert

DobroDeskWidgetExperience

Fehler

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

Fehler

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

DobroDeskWidgetViewController

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

close

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

DobroDeskWidgetBridgePresenter.close(animated: Bool = true)

DobroDeskWidgetBridgePresenter.embed

Zeigt das native Widget mit dem gemeinsamen Widget-Vertrag.

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

Fehler

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

setEmbeddedVisible

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

setEmbeddedVisible(_ visible: Bool)

voiceFactory

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

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

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

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

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