Flutter SDK: Référence API

DobroDeskFlutterClient

Obligatoire

La configuration du framework fournit l'identité de l'application et le périmètre du compte et obtient un jeton d'autorisation récent à courte durée de vie auprès du fournisseur d'identifiants de l'hôte. Les formes du jeton et du résultat suivent la signature de la plateforme affichée.

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

Erreurs

• invalid-config

DobroDeskFlutterClient

Crée le client et valide la configuration.

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

startSession

Démarre une conversation avec un premier message idempotent.

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

Erreurs

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

resumeSession

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

resumeSession(): Future<DobroDeskSession?>

Erreurs

• network
• session-expired
• outbox-corrupt

refresh

Charge l'état actuel de la conversation.

refresh(): Future<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?, afterMessageCount? }): Future<DobroDeskSnapshot>

Erreurs

• realtime-unavailable
• network
• session-expired

sendMessage

Envoie un message et renvoie son état de livraison.

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

Erreurs

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

flushOutbox

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

flushOutbox(): Future<List<DobroDeskAcceptedMessage>>

Erreurs

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession(): Future<void>

Erreurs

• request-in-progress
• outbox-corrupt

setAuthorizationToken

Fournit au pont natif le dernier jeton à courte durée de vie.

setAuthorizationToken(String token): Future<void>

logout

Termine la session et libère les fonctions optionnelles.

logout(): Future<void>

Erreurs

• outbox-corrupt

presentWidget

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

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

Erreurs

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

closeWidget

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

closeWidget(): Future<void>

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: Stream<DobroDeskEvent>

operations

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

operations: DobroDeskOperations

submitForm

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.

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

Renvoie

Future<Object?>

Erreurs

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

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.

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

Renvoie

Future<Object?>

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.

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

Renvoie

Future<Object?>

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.

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

Renvoie

Future<Object?>

Erreurs

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

procedureAction

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

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

Renvoie

Future<Object?>

Erreurs

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

attachmentIntents

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.

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

Renvoie

Future<Object?>

Erreurs

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

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.

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

Renvoie

Future<Object?>

Erreurs

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

listOrders

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

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

Renvoie

Future<Object?>

Erreurs

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

orderDetail

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

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

Renvoie

Future<Object?>

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.

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

Renvoie

Future<Object?>

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.

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

Renvoie

Future<Object?>

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.

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

Renvoie

Future<Object?>

Erreurs

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

DobroDeskClientToolRequest

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: Map<String, Object?> }

DobroDeskClientToolResult

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: Map<String, Object?> }

DobroDeskAttachmentDescriptor

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: int; kind: String (image|video|pdf|text) }

DobroDeskUploadIntent

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 }

DobroDeskLoadingState

L'état de chargement partagé est idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting ou flushing-outbox.

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

DobroDeskEvent

Les événements natifs et des wrappers utilisent l'enveloppe partagée loading, session, snapshot, message accepté, erreur et session effacée.

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

dispose

Arrête le travail des fonctions optionnelles et libère leurs ressources hôte.

dispose(): Future<void>

WidgetExperience (JSON schema)

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

DobroDeskWidgetView

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

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

beginInlineWidget

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

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

Erreurs

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

mountInlineWidget

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

mountInlineWidget(String ownerId): Future<void>

Erreurs

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

disposeInlineWidget

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

disposeInlineWidget(String ownerId): Future<void>

NativeOperation (wrapper bridge)

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

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)

Les ponts de framework encodent la fin d'une action hôte via un pont natif local. Elle n'est pas envoyée comme une opération HTTP par le client natif direct.

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

Renvoie

JsonValue

Erreurs

• field-invalid
• session-expired
• unsupported

attachVoice

Connecte la fonction vocale optionnelle installée par l'hôte.

attachVoice(DobroDeskVoicePort port): Future<DobroDeskVoiceFacade>

Erreurs

• unsupported
• invalid-config

voice

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.

voice: DobroDeskVoiceFacade?

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(): Future<void>; stop(): Future<void>; setMuted(bool muted): Future<void>; bargeIn(): Future<void>; dispose(): Future<void>

Erreurs

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

push module (native only)

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.

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

DobroDeskException

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

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

Erreurs

• 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