Capacitor SDK: Довідник API

DobroDeskSdkConfig

Обов'язковий

Конфігурація фреймворку передає особу застосунку й область облікового запису та отримує свіжий короткоживучий authorization token від credential provider хоста. Форми токена й результату відповідають сигнатурі платформи.

{ apiOrigin: string; integrationId: string; accountScope: string; locale?: SdkLocale; turnstileToken?: string; pollIntervalMs?: number; fetchImpl?: typeof fetch; credentialProvider: () => Promise<{ authorizationToken: string }>; hostActions?: HostActionHandlers; context?: JsonObject }

Помилки

• invalid-config

DobroDeskCapacitorClient

Створює клієнт і перевіряє конфігурацію інтеграції.

new DobroDeskCapacitorClient(config: DobroDeskSdkConfig)

startSession

Починає розмову з ідемпотентним першим повідомленням.

startSession(message: string, options?: Omit<SessionStartInput, 'message'>): Promise<Record<string, unknown>>

Помилки

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

resumeSession

Відновлює стан облікового запису або серверну сесію.

resumeSession(): Promise<Record<string, unknown> | null>

Помилки

• network
• session-expired
• outbox-corrupt

refresh

Завантажує поточний знімок розмови.

refresh(): Promise<Record<string, unknown>>

Помилки

• network
• session-expired
• message-rejected

waitForAssistant

Опитує з обмеженим інтервалом, доки робота асистента не завершиться або не спливе час очікування.

waitForAssistant(options?: Omit<WaitForAssistantOptions, 'pollIntervalMs'>): Promise<Record<string, unknown>>

Помилки

• realtime-unavailable
• network
• session-expired

sendMessage

Надсилає повідомлення та повертає його статус доставки.

sendMessage(text: string, idempotencyKey?: string): Promise<Record<string, unknown>>

Помилки

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

flushOutbox

Повторює очікувані мутації з оригінальним тілом і ключем ідемпотентності.

flushOutbox(): Promise<readonly Record<string, unknown>[]>

Помилки

• network
• outbox-corrupt
• session-expired

resetSession

Очищає сесію, snapshot і очікувані мутації в межах облікового запису.

resetSession(): Promise<void>

Помилки

• request-in-progress
• outbox-corrupt

setAuthorizationToken

Передає найновіший короткоживучий токен нативному мосту.

setAuthorizationToken(token: string): Promise<void>

logout

Завершує сесію клієнта й очищає додаткові можливості.

logout(): Promise<void>

Помилки

• outbox-corrupt

presentWidget

Показує нативний віджет зі спільним контрактом вигляду.

presentWidget(options?: NativeWidgetOptions): Promise<void>

Помилки

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

closeWidget

Закриває поточний нативний показ або звільняє змонтований host.

closeWidget(): Promise<void>

subscribe

Підписує host на канонічні події SDK. Для звільнення listener використовуйте subscription, callback відписки або stream subscription, який повертає платформа.

subscribe(listener: (event: SdkEvent) => void): Promise<{ remove(): Promise<void> }>

operations

Надає типізовані операції форм, client tools, вкладень і commerce через нативний рушій.

operations: DobroDeskRichOperations

submitForm

Надсилає обмежені значення форми розмови, яку надав сервер. Ідентифікатор запиту та значення перевіряються до підписаного нативного запиту.

operations.submitForm(requestId: string, values: JsonObject): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

requestClientTool

Запитує дозволений client tool, підтверджує його результат або читає його стан. Payload інструмента плоский, обмежений і відхиляє чутливі назви полів.

operations.requestClientTool(input: ClientToolRequest): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

completeClientTool

Запитує дозволений client tool, підтверджує його результат або читає його стан. Payload інструмента плоский, обмежений і відхиляє чутливі назви полів.

operations.completeClientTool(input: ClientToolResult): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

clientToolStatus

Запитує дозволений client tool, підтверджує його результат або читає його стан. Payload інструмента плоский, обмежений і відхиляє чутливі назви полів.

operations.clientToolStatus(callId: string): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

procedureAction

Виконує дію серверної процедури з ключем ідемпотентності та очікуваною версією workflow.

operations.procedureAction(input: ProcedureActionInput): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

attachmentIntents

Створює intent для завантаження та передає вибрані локальні файли з урахуванням лімітів розміру, типу, URI і політик SDK.

operations.attachmentIntents(messageId: string, attachments: readonly AttachmentDescriptor[]): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

uploadAttachment

Створює intent для завантаження та передає вибрані локальні файли з урахуванням лімітів розміру, типу, URI і політик SDK.

operations.uploadAttachment(intent: AttachmentUploadIntent, fileUri: string, mimeType: string): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

listOrders

Читає дані замовлення та створює, підтверджує або читає обмежену пропозицію скасування Shopify-замовлення.

operations.listOrders(query?: CommerceOrderQuery): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

orderDetail

Читає дані замовлення та створює, підтверджує або читає обмежену пропозицію скасування Shopify-замовлення.

operations.orderDetail(orderRef: string): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

createCommerceProposal

Читає дані замовлення та створює, підтверджує або читає обмежену пропозицію скасування Shopify-замовлення.

operations.createCommerceProposal(input: CommerceProposalInput, idempotencyKey: string): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

confirmCommerceProposal

Читає дані замовлення та створює, підтверджує або читає обмежену пропозицію скасування Shopify-замовлення.

operations.confirmCommerceProposal(proposalId: string, idempotencyKey: string): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

commerceProposal

Читає дані замовлення та створює, підтверджує або читає обмежену пропозицію скасування Shopify-замовлення.

operations.commerceProposal(proposalId: string): Promise<JsonValue>

Повертає

Promise<JsonValue>

Помилки

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

ClientToolRequest

Запитує дозволений client tool, підтверджує його результат або читає його стан. Payload інструмента плоский, обмежений і відхиляє чутливі назви полів.

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

ClientToolResult

Запитує дозволений client tool, підтверджує його результат або читає його стан. Payload інструмента плоский, обмежений і відхиляє чутливі назви полів.

{ callId: string; output: ClientToolPayload }

AttachmentDescriptor

Створює intent для завантаження та передає вибрані локальні файли з урахуванням лімітів розміру, типу, URI і політик SDK.

{ clientId: string; fileName: string; mimeType: string; sizeBytes: number; kind: AttachmentKind }

AttachmentUploadIntent

Створює intent для завантаження та передає вибрані локальні файли з урахуванням лімітів розміру, типу, URI і політик SDK.

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

CommerceProposalInput

Читає дані замовлення та створює, підтверджує або читає обмежену пропозицію скасування Shopify-замовлення.

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

DobroDeskLoadingState

Спільний стан завантаження має одне зі значень idle, starting-session, loading-messages, sending-message, waiting-for-assistant, executing-action, reconnecting або flushing-outbox.

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

SdkEvent

Події native і wrapper використовують спільний envelope loading, session, snapshot, accepted-message, error і session-cleared.

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

WidgetExperience

Спільний об'єкт appearance-v2: кольори, типографіка, компонування й тіні в задокументованих межах.

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

Помилки

• field-invalid
• unsupported

mountWidget

Показує нативний віджет зі спільним контрактом вигляду.

mountWidget(container: HTMLElement, options?: NativeWidgetOptions, callbacks?: DobroDeskEmbeddedCallbacks): Promise<DobroDeskEmbeddedWidget>

Помилки

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

DobroDeskEmbeddedWidget

Показує нативний віджет зі спільним контрактом вигляду.

setVisible(visible: boolean): void; dispose(): Promise<void>

NativeOperation (wrapper bridge)

Надає типізовані операції форм, client tools, вкладень і commerce через нативний рушій.

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)

Framework-обгортки передають завершення host action через локальний нативний міст. Воно не надсилається як HTTP-операція через прямий нативний клієнт.

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

Повертає

JsonValue

Помилки

• field-invalid
• session-expired
• unsupported

attachVoice

Підключає окремо встановлену голосову можливість, якою керує хост.

attachVoice(port: DobroDeskVoicePort): Promise<DobroDeskVoiceFacade>

Помилки

• unsupported
• invalid-config

voice

Керує опційною голосовою можливістю, встановленою хостом: запуском, зупиненням, вимкненням мікрофона, barge-in і звільненням ресурсів. Віджет у браузері може показувати voice UI, але цей API керує лише голосовим мостом хоста.

voice: DobroDeskVoiceFacade | undefined

createCapacitorVoicePort

Підключає окремо встановлену голосову можливість, якою керує хост.

createCapacitorVoicePort(bridge): DobroDeskVoicePort

voice lifecycle

Керує опційною голосовою можливістю, встановленою хостом: запуском, зупиненням, вимкненням мікрофона, barge-in і звільненням ресурсів. Віджет у браузері може показувати voice UI, але цей API керує лише голосовим мостом хоста.

start(): Promise<void>; stop(): Promise<void>; setMuted(muted: boolean): Promise<void>; bargeIn(): Promise<void>; dispose(): Promise<void>

Помилки

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

push module (native only)

Описує окремий опційний нативний push-артефакт і реєстрацію хоста. Framework-обгортки не експортують JavaScript або Dart push-клієнт; використовуйте нативний модуль iOS або Android.

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

SdkErrorCode

Обробляйте стабільні машинні коди та не показуйте діагностику сервера в UI.

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