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

apiOrigin

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

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

URL

integrationId

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

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

String

accountScope

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

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

String

locale

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

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

String = "en"

credentialProvider

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

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

() async throws -> String

turnstileToken

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

String?

pollInterval

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

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

TimeInterval = 1

DobroDeskClient

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

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

Помилки

• invalid-config
• outbox-corrupt

events

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

events() -> AsyncStream<DobroDeskEvent>

state getters

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

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

loadWidgetAppearance

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

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

Помилки

• network
• http
• session-expired

loadWidgetContent

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

loadWidgetContent() async throws -> DobroDeskWidgetContentSnapshot

Помилки

• network
• http
• field-invalid

startSession

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

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

Помилки

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

resumeSession

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

resumeSession() async throws -> DobroDeskSession?

Помилки

• network
• session-expired
• outbox-corrupt

restoreSession

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

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

Помилки

• session-expired
• network

refresh

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

refresh() async throws -> DobroDeskSnapshot

Помилки

• network
• session-expired
• message-rejected

waitForAssistant

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

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

Помилки

• realtime-unavailable
• network
• session-expired

sendMessage

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

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

Помилки

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

attachments

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

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

Помилки

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

performOperation / performNativeOperation

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

performOperation(requestJson: String) async throws -> 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 }[] } }

flushOutbox

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

flushOutbox() async throws -> [DobroDeskAcceptedMessage]

Помилки

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() async throws

Помилки

• request-in-progress
• outbox-corrupt

WidgetExperience

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

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

Помилки

• field-invalid
• unsupported

reducedMotion

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

system | always

DobroDeskWidgetLocaleCatalog.copy(for:)

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

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

Помилки

• field-invalid

DobroDeskWidgetCopy.init(values:)

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

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

Помилки

• field-invalid

DobroDeskWidgetCopy.requiredKeys

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

Set<String>

DobroDeskWidgetExperience.decodeAndResolve

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

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

Повертає

DobroDeskWidgetExperience

Помилки

• field-invalid
• unsupported

DobroDeskWidgetExperience.resolve

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

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

Повертає

DobroDeskWidgetExperience

Помилки

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

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

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

Помилки

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

DobroDeskWidgetViewController

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

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

close

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

DobroDeskWidgetBridgePresenter.close(animated: Bool = true)

DobroDeskWidgetBridgePresenter.embed

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

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

Помилки

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

setEmbeddedVisible

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

setEmbeddedVisible(_ visible: Bool)

voiceFactory

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

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

Помилки

• unsupported
• invalid-config

voice lifecycle

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

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

Помилки

• 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

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