Android 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 | String

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 | suspend () -> String

turnstileToken

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

String?

pollInterval

Valeur par défaut: 1s

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

TimeInterval | Duration = 1s

DobroDeskClient

Crée le client et valide la configuration.

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

Erreurs

• invalid-config
• outbox-corrupt

subscribe

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.

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

state getters

Renvoie l'état actuel du widget sans abonnement.

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

loadWidgetAppearance

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

loadWidgetAppearance(): JsonObject suspend

Erreurs

• network
• http
• session-expired

loadWidgetContent

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

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

Erreurs

• network
• http
• field-invalid

startSession

Démarre une conversation avec un premier message idempotent.

startSession(input: SessionStartInput): DobroDeskSession suspend

Erreurs

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

resumeSession

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

resumeSession(): DobroDeskSession? suspend

Erreurs

• network
• session-expired
• outbox-corrupt

restoreSession

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

restoreSession(restored: DobroDeskSession): ConversationSnapshot suspend

Erreurs

• session-expired
• network

refresh

Charge l'état actuel de la conversation.

refresh(): ConversationSnapshot suspend

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

Erreurs

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

sendMessage

Envoie un message et renvoie son état de livraison.

sendMessage(input: MessageInput): AcceptedMessage suspend

Erreurs

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

attachments

Envoie un message et renvoie son état de livraison.

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

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.

performNativeOperation(requestJson: String, resolveFile: suspend (String, String) -> DobroDeskAttachmentSource): 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 }[] } }

requestAttachmentIntents

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.

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

Erreurs

• attachment_policy_failed
• session-expired
• network
• http

uploadAttachment

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.

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

Erreurs

• attachment_policy_failed
• session-expired
• network
• http

downloadAttachment

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.

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

Erreurs

• attachment_policy_failed
• session-expired
• network
• http

canDownloadAttachment

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.

canDownloadAttachment(downloadUrl: String): Boolean

requestClientTool

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.

requestClientTool(requestInput: DobroDeskClientToolRequest) suspend -> DobroDeskClientToolResponse

Erreurs

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

completeClientTool

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.

completeClientTool(result: DobroDeskClientToolResult) suspend -> DobroDeskClientToolResponse

Erreurs

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

clientToolStatus

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.

clientToolStatus(callId: String) suspend -> DobroDeskClientToolResponse

Erreurs

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

submitConversationForm

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.

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

Erreurs

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

performProcedureAction

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

performProcedureAction(action: DobroDeskProcedureActionRequest) suspend -> Unit

Erreurs

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

loadCommerceOrders

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

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

Erreurs

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

loadCommerceOrderDetail

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

loadCommerceOrderDetail(orderReference: String) suspend -> JsonElement?

Erreurs

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

createCommerceProposal

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

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

Erreurs

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

confirmCommerceProposal

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

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

Erreurs

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

commerceProposal

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

commerceProposal(proposalId: String) suspend -> JsonElement?

Erreurs

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

flushOutbox

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

flushOutbox(): List<AcceptedMessage> suspend

Erreurs

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() suspend

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

WidgetLocaleCopies.forLocale

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.

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

Erreurs

• field-invalid

WidgetCopy(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.

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

Erreurs

• field-invalid

WidgetCopy.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>

WidgetCopy.text

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.

WidgetCopy.text(key: String): String

Erreurs

• field-invalid

WidgetExperience.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.

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

Renvoie

WidgetExperience

Erreurs

• field-invalid
• unsupported

WidgetExperience.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.

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

Renvoie

WidgetExperience

Erreurs

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

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

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

Erreurs

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

close / detach

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

close(): Unit; detach(): Unit

DobroDeskWidgetBridgePresenter.createEmbedded

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

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

Erreurs

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

DobroDeskWidgetEmbeddedHandle

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

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

voiceFactory

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

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

start(), stop(), setMuted(), bargeIn(), dispose()

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; Android: com.dobrodesk:dobrodesk-push:<version>

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 | ATTACHMENT_POLICY_FAILED | ATTACHMENT_RATE_LIMITED | ACTION_IDENTITY_REQUIRED | COMMERCE_IDENTITY_REQUIRED | COMMERCE_UNAVAILABLE | SHOPIFY_RECONNECT_REQUIRED | SHOPIFY_RATE_LIMITED | NOT_FOUND