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

apiOrigin

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

У продакшені API origin має бути HTTPS. Нативні клієнти дозволяють HTTP localhost для розробки.

URL | String

integrationId

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

Публічний ідентифікатор інтеграції з каналу віджета DobroDesk.

String

accountScope

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

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

String

locale

Значення за замовчуванням: en

Локаль віджета для контенту. Web за замовчуванням використовує auto; нативні bundle зараз підтримують en, uk, de та es.

String = "en"

credentialProvider

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

Функція бекенду, що повертає короткоживучий підписаний JWT клієнта. Секрет підпису не можна зберігати в застосунку.

() async throws -> String | suspend () -> String

turnstileToken

Опційний токен Turnstile для інтеграцій, яким він потрібен.

String?

pollInterval

Значення за замовчуванням: 1s

Обмежений інтервал опитування під час очікування асинхронної відповіді асистента.

TimeInterval | Duration = 1s

DobroDeskClient

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

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

Помилки

• invalid-config
• outbox-corrupt

subscribe

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

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

state getters

Повертає поточний стан віджета без підписки.

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

loadWidgetAppearance

Завантажує перевірений appearance або content bundle нативного віджета.

loadWidgetAppearance(): JsonObject suspend

Помилки

• network
• http
• session-expired

loadWidgetContent

Завантажує перевірений appearance або content bundle нативного віджета.

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

Помилки

• network
• http
• field-invalid

startSession

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

startSession(input: SessionStartInput): DobroDeskSession suspend

Помилки

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

resumeSession

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

resumeSession(): DobroDeskSession? suspend

Помилки

• network
• session-expired
• outbox-corrupt

restoreSession

Відновлює переданий прийнятий доказ сесії та завантажує її snapshot.

restoreSession(restored: DobroDeskSession): ConversationSnapshot suspend

Помилки

• session-expired
• network

refresh

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

refresh(): ConversationSnapshot suspend

Помилки

• network
• session-expired
• message-rejected

waitForAssistant

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

waitForAssistant(timeout: Duration = Duration.ofSeconds(30), afterMessageCount: Int? = null): ConversationSnapshot suspend

Помилки

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

sendMessage

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

sendMessage(input: MessageInput): AcceptedMessage suspend

Помилки

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

attachments

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

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

Помилки

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

performOperation / performNativeOperation

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

performNativeOperation(requestJson: String, resolveFile: suspend (String, String) -> DobroDeskAttachmentSource): String

Помилки

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

NativeOperation

Повертає декодований JSON із нативного мосту операцій. Обробляйте перевірку, транспорт, завершення сесії та відмову сервера як окремі результати.

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"

Помилки

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

submit-form request

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

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

Повертає

JsonValue

Помилки

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

request-client-tool request

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

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

Повертає

JsonValue

Помилки

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

complete-client-tool request

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

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

Повертає

JsonValue

Помилки

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

client-tool-status request

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

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

Повертає

JsonValue

Помилки

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

procedure-action request

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

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

Повертає

JsonValue

Помилки

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

attachment-intents request

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

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

Повертає

JsonValue

Помилки

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

upload-attachment request

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

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

Повертає

JsonValue

Помилки

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

list-orders request

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

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

Повертає

JsonValue

Помилки

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

order-detail request

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

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

Повертає

JsonValue

Помилки

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

create-commerce-proposal request

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

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

Повертає

JsonValue

Помилки

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

confirm-commerce-proposal request

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

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

Повертає

JsonValue

Помилки

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

commerce-proposal request

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

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

Повертає

JsonValue

Помилки

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

NativeOperationBridgeResult

Повертає декодований JSON із нативного мосту операцій. Обробляйте перевірку, транспорт, завершення сесії та відмову сервера як окремі результати.

{ valueJson: string }

Повертає

JsonValue

Помилки

• http

HostActionResult

Дозволені callback-функції застосунку для керованих дій віджета. Вони не автентифікують мережеві запити.

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

ClientToolRequest

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

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

ClientToolResult

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

{ callId: string; output: ClientToolPayload }

ProcedureActionInput

Виконує дію серверної процедури з ключем ідемпотентності та очікуваною версією 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

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

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

AttachmentUploadIntent

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

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

CommerceOrderQuery

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

{ cursor?: string; store?: string }

CommerceProposalInput

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

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

requestAttachmentIntents

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

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

Помилки

• attachment_policy_failed
• session-expired
• network
• http

uploadAttachment

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

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

Помилки

• attachment_policy_failed
• session-expired
• network
• http

downloadAttachment

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

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

Помилки

• attachment_policy_failed
• session-expired
• network
• http

canDownloadAttachment

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

canDownloadAttachment(downloadUrl: String): Boolean

requestClientTool

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

requestClientTool(requestInput: DobroDeskClientToolRequest) suspend -> DobroDeskClientToolResponse

Помилки

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

completeClientTool

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

completeClientTool(result: DobroDeskClientToolResult) suspend -> DobroDeskClientToolResponse

Помилки

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

clientToolStatus

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

clientToolStatus(callId: String) suspend -> DobroDeskClientToolResponse

Помилки

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

submitConversationForm

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

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

Помилки

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

performProcedureAction

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

performProcedureAction(action: DobroDeskProcedureActionRequest) suspend -> Unit

Помилки

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

loadCommerceOrders

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

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

Помилки

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

loadCommerceOrderDetail

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

loadCommerceOrderDetail(orderReference: String) suspend -> JsonElement?

Помилки

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

createCommerceProposal

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

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

Помилки

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

confirmCommerceProposal

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

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

Помилки

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

commerceProposal

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

commerceProposal(proposalId: String) suspend -> JsonElement?

Помилки

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

flushOutbox

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

flushOutbox(): List<AcceptedMessage> suspend

Помилки

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() suspend

Помилки

• request-in-progress
• outbox-corrupt

WidgetExperience

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

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

Помилки

• field-invalid
• unsupported

reducedMotion

За замовчуванням використовуйте системне налаштування. Нативні хости також враховують доступність, економію енергії та термальний стан.

system | always

WidgetLocaleCopies.forLocale

Завантажує вбудовану нативну мапу основних текстів віджета. Каталог перевіряє спільний контракт і наразі містить en, uk, de та es; похідні підписи процедур, ролей і валідації є окремими.

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

Помилки

• field-invalid

WidgetCopy(values)

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

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

Помилки

• field-invalid

WidgetCopy.requiredKeys

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

Set<String>

WidgetCopy.text

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

WidgetCopy.text(key: String): String

Помилки

• field-invalid

WidgetExperience.decodeAndResolve

Декодує та розв'язує спільний контракт дизайну з платформними override, override текстів і системним станом зменшення руху хоста.

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

Повертає

WidgetExperience

Помилки

• field-invalid
• unsupported

WidgetExperience.resolve

Декодує та розв'язує спільний контракт дизайну з платформними override, override текстів і системним станом зменшення руху хоста.

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

Повертає

WidgetExperience

Помилки

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

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

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

Помилки

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

close / detach

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

close(): Unit; detach(): Unit

DobroDeskWidgetBridgePresenter.createEmbedded

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

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

Помилки

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

DobroDeskWidgetEmbeddedHandle

Налаштування нативної навігації та показу web launcher або панелі.

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

voiceFactory

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

DobroDeskWidgetBridgePresenter.installVoiceFactory(factory); uninstallVoiceFactory()

Помилки

• unsupported
• invalid-config

voice lifecycle

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

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

Помилки

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

push

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

iOS: DobroDeskPush product; 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 | ATTACHMENT_POLICY_FAILED | ATTACHMENT_RATE_LIMITED | ACTION_IDENTITY_REQUIRED | COMMERCE_IDENTITY_REQUIRED | COMMERCE_UNAVAILABLE | SHOPIFY_RECONNECT_REQUIRED | SHOPIFY_RATE_LIMITED | NOT_FOUND