iOS SDK: Référence API

apiOrigin

Obligatoire

L'origine de l'API utilise HTTPS en production. Les clients natifs autorisent HTTP sur localhost pour le développement.

URL

integrationId

Obligatoire

Identifiant d'intégration public copié depuis le canal de widget DobroDesk.

String

accountScope

Obligatoire

Clé stable du client ou du compte qui isole l'état durable de la session et de la boîte d'envoi.

String

locale

Valeur par défaut: en

Locale du widget pour le contenu. Le web utilise auto par défaut; les bundles natifs prennent actuellement en, uk, de et es en charge.

String = "en"

credentialProvider

Obligatoire

Une fonction backend qui renvoie un JWT client signé et de courte durée. Le secret de signature reste hors de l'application.

() async throws -> String

turnstileToken

Jeton Turnstile facultatif pour les intégrations qui l'exigent.

String?

pollInterval

Valeur par défaut: 1

Intervalle limité utilisé pour interroger une réponse asynchrone de l'assistant.

TimeInterval = 1

DobroDeskClient

Crée le client et valide la configuration.

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

Erreurs

• invalid-config
• outbox-corrupt

events

S'abonne aux événements canoniques du SDK. Pour libérer l'écouteur, utilisez l'abonnement, le callback d'annulation ou l'abonnement au flux renvoyé par la plateforme.

events() -> AsyncStream<DobroDeskEvent>

state getters

Renvoie l'état actuel du widget sans abonnement.

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

loadWidgetAppearance

Charge le bundle d'apparence ou de contenu validé pour le widget natif.

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

Erreurs

• network
• http
• session-expired

loadWidgetContent

Charge le bundle d'apparence ou de contenu validé pour le widget natif.

loadWidgetContent() async throws -> DobroDeskWidgetContentSnapshot

Erreurs

• network
• http
• field-invalid

startSession

Démarre une conversation avec un premier message idempotent.

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

Erreurs

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

resumeSession

Restaure l'état du compte ou une session serveur.

resumeSession() async throws -> DobroDeskSession?

Erreurs

• network
• session-expired
• outbox-corrupt

restoreSession

Restaure une preuve de session acceptée et charge son snapshot.

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

Erreurs

• session-expired
• network

refresh

Charge l'état actuel de la conversation.

refresh() async throws -> DobroDeskSnapshot

Erreurs

• network
• session-expired
• message-rejected

waitForAssistant

Interroge avec un délai limité jusqu'à la fin du travail de l'assistant ou l'expiration de l'attente.

waitForAssistant(timeout: TimeInterval = 30, afterMessageCount: Int? = nil) async throws -> DobroDeskSnapshot

Erreurs

• realtime-unavailable
• network
• session-expired

sendMessage

Envoie un message et renvoie son état de livraison.

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

Erreurs

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

attachments

Envoie un message et renvoie son état de livraison.

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

Erreurs

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

performOperation / performNativeOperation

Expose des opérations typées de formulaires, outils client, pièces jointes et commerce via le moteur natif.

performOperation(requestJson: String) async throws -> String

Erreurs

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

NativeOperation

Renvoie le JSON décodé par le pont natif des opérations. Traitez validation, transport, expiration et refus du serveur comme des résultats explicites.

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"

Erreurs

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

submit-form request

Envoie des valeurs limitées pour un formulaire de conversation fourni par le serveur. L'identifiant et les valeurs sont validés avant la requête native signée.

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

Renvoie

JsonValue

Erreurs

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

request-client-tool request

Demande un outil client autorisé, confirme son résultat ou lit son état. Les payloads sont plats, limités et refusent les noms de champs sensibles.

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

Renvoie

JsonValue

Erreurs

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

complete-client-tool request

Demande un outil client autorisé, confirme son résultat ou lit son état. Les payloads sont plats, limités et refusent les noms de champs sensibles.

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

Renvoie

JsonValue

Erreurs

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

client-tool-status request

Demande un outil client autorisé, confirme son résultat ou lit son état. Les payloads sont plats, limités et refusent les noms de champs sensibles.

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

Renvoie

JsonValue

Erreurs

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

procedure-action request

Fait progresser une action de procédure fournie par le serveur avec une clé d'idempotence et la révision attendue du workflow.

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

Renvoie

JsonValue

Erreurs

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

attachment-intents request

Crée des intents d'envoi et téléverse les fichiers locaux sélectionnés dans les limites de taille, type, URI et politique du SDK.

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

Renvoie

JsonValue

Erreurs

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

upload-attachment request

Crée des intents d'envoi et téléverse les fichiers locaux sélectionnés dans les limites de taille, type, URI et politique du SDK.

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

Renvoie

JsonValue

Erreurs

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

list-orders request

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

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

Renvoie

JsonValue

Erreurs

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

order-detail request

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

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

Renvoie

JsonValue

Erreurs

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

create-commerce-proposal request

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

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

Renvoie

JsonValue

Erreurs

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

confirm-commerce-proposal request

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

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

Renvoie

JsonValue

Erreurs

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

commerce-proposal request

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

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

Renvoie

JsonValue

Erreurs

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

NativeOperationBridgeResult

Renvoie le JSON décodé par le pont natif des opérations. Traitez validation, transport, expiration et refus du serveur comme des résultats explicites.

{ valueJson: string }

Renvoie

JsonValue

Erreurs

• http

HostActionResult

Callbacks d'application autorisés pour les actions guidées du widget. Ils n'authentifient pas les requêtes réseau.

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

ClientToolRequest

Demande un outil client autorisé, confirme son résultat ou lit son état. Les payloads sont plats, limités et refusent les noms de champs sensibles.

{ toolName: string; basisMessageId: string; input: ClientToolPayload }

ClientToolResult

Demande un outil client autorisé, confirme son résultat ou lit son état. Les payloads sont plats, limités et refusent les noms de champs sensibles.

{ callId: string; output: ClientToolPayload }

ProcedureActionInput

Fait progresser une action de procédure fournie par le serveur avec une clé d'idempotence et la révision attendue du workflow.

{ 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

Crée des intents d'envoi et téléverse les fichiers locaux sélectionnés dans les limites de taille, type, URI et politique du SDK.

{ clientId: string; fileName: string; mimeType: string; sizeBytes: number; kind: "image" | "video" | "pdf" | "text" }

AttachmentUploadIntent

Crée des intents d'envoi et téléverse les fichiers locaux sélectionnés dans les limites de taille, type, URI et politique du SDK.

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

CommerceOrderQuery

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

{ cursor?: string; store?: string }

CommerceProposalInput

Lit les données de commande et crée, confirme ou lit une proposition limitée d'annulation de commande Shopify.

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

flushOutbox

Rejoue les mutations en attente avec le corps et la clé d'origine.

flushOutbox() async throws -> [DobroDeskAcceptedMessage]

Erreurs

• network
• outbox-corrupt
• session-expired

resetSession

Efface la session, le snapshot et les mutations en attente associés au compte.

resetSession() async throws

Erreurs

• request-in-progress
• outbox-corrupt

WidgetExperience

Objet partagé appearance-v2: couleurs, typographie, mise en page et ombre dans les limites documentées.

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

Erreurs

• field-invalid
• unsupported

reducedMotion

Par défaut, le système et les politiques natives d'accessibilité, d'énergie et de température sont suivis.

system | always

DobroDeskWidgetLocaleCatalog.copy(for:)

Charge une carte native intégrée pour les textes principaux du widget. Le catalogue valide ce contrat partagé et inclut actuellement en, uk, de et es; les libellés dérivés des procédures, rôles et validations sont séparés.

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

Erreurs

• field-invalid

DobroDeskWidgetCopy.init(values:)

Construit ou lit les textes partagés validés du widget. Les valeurs inconnues, manquantes, vides ou trop longues sont refusées avant l'affichage.

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

Erreurs

• field-invalid

DobroDeskWidgetCopy.requiredKeys

Construit ou lit les textes partagés validés du widget. Les valeurs inconnues, manquantes, vides ou trop longues sont refusées avant l'affichage.

Set<String>

DobroDeskWidgetExperience.decodeAndResolve

Décode et résout le contrat de design partagé avec les remplacements de plateforme et de textes ainsi que l'état système de réduction des mouvements de l'hôte.

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

Renvoie

DobroDeskWidgetExperience

Erreurs

• field-invalid
• unsupported

DobroDeskWidgetExperience.resolve

Décode et résout le contrat de design partagé avec les remplacements de plateforme et de textes ainsi que l'état système de réduction des mouvements de l'hôte.

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

Renvoie

DobroDeskWidgetExperience

Erreurs

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Présente le widget natif avec le contrat partagé.

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

Erreurs

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

DobroDeskWidgetViewController

Présente le widget natif avec le contrat partagé.

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

close

Ferme la présentation native actuelle ou libère un hôte monté.

DobroDeskWidgetBridgePresenter.close(animated: Bool = true)

DobroDeskWidgetBridgePresenter.embed

Présente le widget natif avec le contrat partagé.

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

Erreurs

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

setEmbeddedVisible

Options de navigation native et de présentation du launcher ou du panneau web.

setEmbeddedVisible(_ visible: Bool)

voiceFactory

Installe ou retire la fabrique vocale native optionnelle utilisée par les présentations du widget.

DobroDeskWidgetBridgePresenter.installVoiceFactory(_ factory: DobroDeskWidgetVoiceFactory); uninstallVoiceFactory()

Erreurs

• unsupported
• invalid-config

voice lifecycle

Contrôle une fonction vocale optionnelle installée par l'hôte: démarrage, arrêt, silencieux, barge-in et libération. Le widget web peut afficher une interface vocale, mais cette API du SDK contrôle uniquement un pont vocal fourni par l'hôte.

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

Erreurs

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

push

Décrit l'artefact push natif optionnel et l'enregistrement de l'hôte. Les wrappers de framework n'exportent pas de client push JavaScript ou Dart ; utilisez le module natif iOS ou Android.

iOS: DobroDeskPush product

SdkErrorCode

Gérez les codes stables lisibles par machine et gardez les diagnostics du serveur hors de l'interface client.

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