Android 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 | String

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 | suspend () -> String

turnstileToken

Token de Turnstile opcional para las integraciones que lo requieren.

String?

pollInterval

Valor predeterminado: 1s

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

TimeInterval | Duration = 1s

DobroDeskClient

Crea el cliente y valida la configuración.

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

Errores

• invalid-config
• outbox-corrupt

subscribe

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.

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

state getters

Devuelve el estado actual del widget sin suscribirse.

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

loadWidgetAppearance

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

loadWidgetAppearance(): JsonObject suspend

Errores

• network
• http
• session-expired

loadWidgetContent

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

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

Errores

• network
• http
• field-invalid

startSession

Inicia una conversación con un primer mensaje idempotente.

startSession(input: SessionStartInput): DobroDeskSession suspend

Errores

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

resumeSession

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

resumeSession(): DobroDeskSession? suspend

Errores

• network
• session-expired
• outbox-corrupt

restoreSession

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

restoreSession(restored: DobroDeskSession): ConversationSnapshot suspend

Errores

• session-expired
• network

refresh

Carga el estado actual de la conversación.

refresh(): ConversationSnapshot suspend

Errores

• network
• session-expired
• message-rejected

waitForAssistant

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

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

Errores

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

sendMessage

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

sendMessage(input: MessageInput): AcceptedMessage suspend

Errores

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

attachments

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

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

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.

performNativeOperation(requestJson: String, resolveFile: suspend (String, String) -> DobroDeskAttachmentSource): 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 }[] } }

requestAttachmentIntents

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

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

Errores

• attachment_policy_failed
• session-expired
• network
• http

uploadAttachment

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

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

Errores

• attachment_policy_failed
• session-expired
• network
• http

downloadAttachment

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

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

Errores

• attachment_policy_failed
• session-expired
• network
• http

canDownloadAttachment

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

canDownloadAttachment(downloadUrl: String): Boolean

requestClientTool

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

requestClientTool(requestInput: DobroDeskClientToolRequest) suspend -> DobroDeskClientToolResponse

Errores

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

completeClientTool

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

completeClientTool(result: DobroDeskClientToolResult) suspend -> DobroDeskClientToolResponse

Errores

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

clientToolStatus

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

clientToolStatus(callId: String) suspend -> DobroDeskClientToolResponse

Errores

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

submitConversationForm

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.

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

Errores

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

performProcedureAction

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

performProcedureAction(action: DobroDeskProcedureActionRequest) suspend -> Unit

Errores

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

loadCommerceOrders

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

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

Errores

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

loadCommerceOrderDetail

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

loadCommerceOrderDetail(orderReference: String) suspend -> JsonElement?

Errores

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

createCommerceProposal

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

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

Errores

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

confirmCommerceProposal

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

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

Errores

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

commerceProposal

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

commerceProposal(proposalId: String) suspend -> JsonElement?

Errores

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

flushOutbox

Reintenta mutaciones pendientes con el cuerpo y la clave originales.

flushOutbox(): List<AcceptedMessage> suspend

Errores

• network
• outbox-corrupt
• session-expired

resetSession

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

resetSession() suspend

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

WidgetLocaleCopies.forLocale

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.

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

Errores

• field-invalid

WidgetCopy(values)

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

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

Errores

• field-invalid

WidgetCopy.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>

WidgetCopy.text

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

WidgetCopy.text(key: String): String

Errores

• field-invalid

WidgetExperience.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.

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

Devuelve

WidgetExperience

Errores

• field-invalid
• unsupported

WidgetExperience.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.

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

Devuelve

WidgetExperience

Errores

• field-invalid
• unsupported

DobroDeskWidgetBridgePresenter.present

Presenta el widget nativo con el contrato compartido.

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

Errores

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

close / detach

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

close(): Unit; detach(): Unit

DobroDeskWidgetBridgePresenter.createEmbedded

Presenta el widget nativo con el contrato compartido.

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

Errores

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

DobroDeskWidgetEmbeddedHandle

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

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

voiceFactory

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

DobroDeskWidgetBridgePresenter.installVoiceFactory(factory); 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.

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

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; Android: com.dobrodesk:dobrodesk-push:<version>

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 | ATTACHMENT_POLICY_FAILED | ATTACHMENT_RATE_LIMITED | ACTION_IDENTITY_REQUIRED | COMMERCE_IDENTITY_REQUIRED | COMMERCE_UNAVAILABLE | SHOPIFY_RECONNECT_REQUIRED | SHOPIFY_RATE_LIMITED | NOT_FOUND