iOS SDK: Referencia de la API

apiOrigin

Obligatorio

El origen de API usa HTTPS en producción. Los clientes nativos permiten HTTP en localhost para desarrollo.

URL

integrationId

Obligatorio

Identificador público de integración copiado del canal de widget de DobroDesk.

String

accountScope

Obligatorio

Clave estable del cliente o la cuenta que aísla el estado persistente de la sesión y la bandeja de salida.

String

locale

Valor predeterminado: en

Locale del widget para el contenido. La web usa auto de forma predeterminada; los bundles nativos admiten actualmente en, uk, de y es.

String = "en"

credentialProvider

Obligatorio

Una función del backend que devuelve un JWT de cliente firmado y de corta duración. El secreto nunca va en la aplicación.

() async throws -> String

turnstileToken

Token de Turnstile opcional para las integraciones que lo requieren.

String?

pollInterval

Valor predeterminado: 1

Intervalo limitado que se usa al consultar una respuesta asíncrona del asistente.

TimeInterval = 1

DobroDeskClient

Crea el cliente y valida la configuración.

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

Errores

• invalid-config
• outbox-corrupt

events

Se suscribe a eventos canónicos del SDK. Para liberar el listener, usa la suscripción, el callback de cancelación o la suscripción de stream que devuelve la plataforma.

events() -> AsyncStream<DobroDeskEvent>

state getters

Devuelve el estado actual del widget sin suscribirse.

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

loadWidgetAppearance

Carga el bundle validado de apariencia o contenido para el widget nativo.

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

Errores

• network
• http
• session-expired

loadWidgetContent

Carga el bundle validado de apariencia o contenido para el widget nativo.

loadWidgetContent() async throws -> DobroDeskWidgetContentSnapshot

Errores

• network
• http
• field-invalid

startSession

Inicia una conversación con un primer mensaje idempotente.

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

Errores

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

resumeSession

Restaura el estado de la cuenta o una sesión del servidor.

resumeSession() async throws -> DobroDeskSession?

Errores

• network
• session-expired
• outbox-corrupt

restoreSession

Restaura una prueba de sesión aceptada y carga su snapshot.

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

Errores

• session-expired
• network

refresh

Carga el estado actual de la conversación.

refresh() async throws -> DobroDeskSnapshot

Errores

• network
• session-expired
• message-rejected

waitForAssistant

Consulta con tiempos limitados hasta que termina el trabajo del asistente o expira la espera.

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

Errores

• realtime-unavailable
• network
• session-expired

sendMessage

Envía un mensaje y devuelve su estado de entrega.

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

Errores

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

attachments

Envía un mensaje y devuelve su estado de entrega.

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

Errores

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

performOperation / performNativeOperation

Expone operaciones tipadas de formularios, herramientas del cliente, adjuntos y comercio mediante el motor nativo.

performOperation(requestJson: String) async throws -> String

Errores

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

NativeOperation

Devuelve JSON decodificado desde el puente nativo de operaciones. Trata la validación, el transporte, la expiración y el rechazo del servidor como resultados explícitos.

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"

Errores

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

submit-form request

Envía valores acotados para un formulario de conversación proporcionado por el servidor. El identificador y los valores se validan antes de la solicitud nativa firmada.

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

Devuelve

JsonValue

Errores

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

request-client-tool request

Solicita una herramienta de cliente permitida, confirma su resultado o consulta su estado. Los payloads son planos, acotados y rechazan nombres de campos sensibles.

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

Devuelve

JsonValue

Errores

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

complete-client-tool request

Solicita una herramienta de cliente permitida, confirma su resultado o consulta su estado. Los payloads son planos, acotados y rechazan nombres de campos sensibles.

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

Devuelve

JsonValue

Errores

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

client-tool-status request

Solicita una herramienta de cliente permitida, confirma su resultado o consulta su estado. Los payloads son planos, acotados y rechazan nombres de campos sensibles.

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

Devuelve

JsonValue

Errores

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

procedure-action request

Avanza una acción de procedimiento proporcionada por el servidor con una clave de idempotencia y la revisión de flujo esperada.

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

Devuelve

JsonValue

Errores

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

attachment-intents request

Crea intenciones de carga y sube archivos locales seleccionados dentro de los límites de tamaño, tipo, URI y política del SDK.

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

Devuelve

JsonValue

Errores

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

upload-attachment request

Crea intenciones de carga y sube archivos locales seleccionados dentro de los límites de tamaño, tipo, URI y política del SDK.

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

Devuelve

JsonValue

Errores

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

list-orders request

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

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

Devuelve

JsonValue

Errores

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

order-detail request

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

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

Devuelve

JsonValue

Errores

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

create-commerce-proposal request

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

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

Devuelve

JsonValue

Errores

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

confirm-commerce-proposal request

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

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

Devuelve

JsonValue

Errores

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

commerce-proposal request

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

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

Devuelve

JsonValue

Errores

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

NativeOperationBridgeResult

Devuelve JSON decodificado desde el puente nativo de operaciones. Trata la validación, el transporte, la expiración y el rechazo del servidor como resultados explícitos.

{ valueJson: string }

Devuelve

JsonValue

Errores

• http

HostActionResult

Callbacks permitidos de la aplicación para acciones guiadas del widget. No autentican solicitudes de red.

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

ClientToolRequest

Solicita una herramienta de cliente permitida, confirma su resultado o consulta su estado. Los payloads son planos, acotados y rechazan nombres de campos sensibles.

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

ClientToolResult

Solicita una herramienta de cliente permitida, confirma su resultado o consulta su estado. Los payloads son planos, acotados y rechazan nombres de campos sensibles.

{ callId: string; output: ClientToolPayload }

ProcedureActionInput

Avanza una acción de procedimiento proporcionada por el servidor con una clave de idempotencia y la revisión de flujo esperada.

{ 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

Crea intenciones de carga y sube archivos locales seleccionados dentro de los límites de tamaño, tipo, URI y política del SDK.

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

AttachmentUploadIntent

Crea intenciones de carga y sube archivos locales seleccionados dentro de los límites de tamaño, tipo, URI y política del SDK.

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

CommerceOrderQuery

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

{ cursor?: string; store?: string }

CommerceProposalInput

Lee datos de pedidos y crea, confirma o consulta una propuesta acotada para cancelar un pedido de Shopify.

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

flushOutbox

Reintenta mutaciones pendientes con el cuerpo y la clave originales.

flushOutbox() async throws -> [DobroDeskAcceptedMessage]

Errores

• network
• outbox-corrupt
• session-expired

resetSession

Borra la sesión, el snapshot y las mutaciones pendientes asociadas a la cuenta.

resetSession() async throws

Errores

• request-in-progress
• outbox-corrupt

WidgetExperience

Objeto compartido appearance-v2: colores, tipografía, diseño y sombra dentro de los límites documentados.

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

Errores

• field-invalid
• unsupported

reducedMotion

De forma predeterminada sigue el sistema y las políticas nativas de accesibilidad, batería y temperatura.

system | always

DobroDeskWidgetLocaleCatalog.copy(for:)

Carga un mapa de textos principales del widget incluido en el SDK nativo. El catálogo valida ese contrato compartido e incluye actualmente en, uk, de y es; las etiquetas derivadas de procedimientos, roles y validación son independientes.

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

Errores

• field-invalid

DobroDeskWidgetCopy.init(values:)

Crea o lee los textos compartidos validados del widget. Los valores desconocidos, ausentes, vacíos o demasiado largos se rechazan antes de renderizar.

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

Errores

• field-invalid

DobroDeskWidgetCopy.requiredKeys

Crea o lee los textos compartidos validados del widget. Los valores desconocidos, ausentes, vacíos o demasiado largos se rechazan antes de renderizar.

Set<String>

DobroDeskWidgetExperience.decodeAndResolve

Decodifica y resuelve el contrato de diseño compartido con overrides de plataforma, de textos y el estado del sistema del host para reducir el movimiento.

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

Devuelve

DobroDeskWidgetExperience

Errores

• field-invalid
• unsupported

DobroDeskWidgetExperience.resolve

Decodifica y resuelve el contrato de diseño compartido con overrides de plataforma, de textos y el estado del sistema del host para reducir el movimiento.

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

Devuelve

DobroDeskWidgetExperience

Errores

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Presenta el widget nativo con el contrato compartido.

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

Errores

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

DobroDeskWidgetViewController

Presenta el widget nativo con el contrato compartido.

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

close

Cierra la presentación nativa actual o libera un host montado.

DobroDeskWidgetBridgePresenter.close(animated: Bool = true)

DobroDeskWidgetBridgePresenter.embed

Presenta el widget nativo con el contrato compartido.

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

Errores

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

setEmbeddedVisible

Opciones de navegación nativa y de presentación del launcher o panel web.

setEmbeddedVisible(_ visible: Bool)

voiceFactory

Instala o elimina la fábrica de voz nativa opcional usada por las presentaciones del widget.

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

Errores

• unsupported
• invalid-config

voice lifecycle

Controla una capacidad de voz opcional instalada por el host: inicio, detención, silencio, barge-in y liberación. El widget web puede mostrar una interfaz de voz, pero esta API del SDK solo controla un puente de voz proporcionado por el host.

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

Errores

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

push

Describe el artefacto push nativo opcional y el registro del host. Los wrappers de framework no exportan un cliente push de JavaScript o Dart; usa el módulo nativo de iOS o Android.

iOS: DobroDeskPush product

SdkErrorCode

Gestiona códigos estables legibles por máquinas y mantén los diagnósticos del servidor fuera de la interfaz del cliente.

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