SDK de dispositivos móviles sin interfaz gráfica para Android: Acciones inteligentes, archivos adjuntos y desvío

En este documento, se muestra cómo integrar y personalizar el SDK de Headless Mobile en tu aplicación para Android. Abarca las acciones inteligentes, los archivos adjuntos y la desviación.

Configura acciones y archivos adjuntos inteligentes

Las acciones inteligentes permiten que los agentes y los consumidores intercambien información enriquecida y estructurada, como fotos, videos, fragmentos de texto y verificación biométrica.

En la arquitectura sin interfaz gráfica, el SDK actúa estrictamente como la capa de transporte segura. Te indica cuándo se requiere o solicita una acción, y transporta los datos de forma segura a la plataforma de CCAI Platform. Como eres propietario de la interfaz de usuario, tu app es completamente responsable de crear las pantallas de la cámara, los selectores de fotos y los cuadros de texto, y de activar las indicaciones biométricas integradas de Android.

Acciones inteligentes previas a la sesión

Las acciones previas a la sesión recopilan contexto (como un número de cuenta o un video de un producto roto) antes de que el usuario se una a la fila, lo que reduce significativamente el tiempo de atención del agente.

Qué proporciona el SDK: Las reglas y los requisitos para una fila específica (por ejemplo, si la verificación biométrica, la carga de fotos o la entrada de texto son opcionales o obligatorias antes de unirse).

Qué compilarás: Las pantallas de la IU previas a la sesión (cámara, entrada de texto y mensajes biométricos) que aparecen entre el momento en que el usuario presiona una fila y el momento en que ingresa a la sala de espera, así como la lógica de almacenamiento en caché en disco para conservar de forma segura el contenido multimedia hasta que se conecte la sesión.

Ejemplo de implementación

Este código verifica la configuración del SDK para ver si la cola elegida tiene requisitos previos a la sesión. Muestra cómo controlar un requisito de video manteniendo una referencia de archivo Uri en el disco en lugar de mantener el video en la memoria.

// 1. Check requirements and collect data BEFORE joining the queue
fun checkPreSessionRequirements(queueMenu: QueueMenu) {
    val smartActions = queueMenu.settings
    if (smartActions.isNullOrEmpty()) {
        startChat(queueMenu)
        return
    }

    // Example: handle a video requirement
    presentVideoPicker { localFileUri ->
        // IMPORTANT: localFileUri should point to context.cacheDir
        MySessionStateManager.pendingPreSessionVideo = localFileUri
        startChat(queueMenu)
    }
}

// 2. Upload and clean up AFTER the session officially connects
fun handleSessionConnected() {
    val pendingVideoUri = MySessionStateManager.pendingPreSessionVideo ?: return

    // Upload using the standard in-session pipeline
    // then clean up the temporary file
    val file = File(pendingVideoUri.path ?: return)
    file.delete()
    MySessionStateManager.pendingPreSessionVideo = null
}

Leer la configuración de la acción inteligente previa a la sesión

El SDK expone la configuración de las acciones inteligentes previas a la sesión a través de dos rutas complementarias. Verifica ambos para determinar si se requiere la captura previa a la sesión para una fila y un canal determinados.

Ruta A: Nivel de la fila (QueueMenu.settings[].sdk.preSessionSmartAction)

// `QueueMenuSetting` and `QueueMenuSDKSetting` (simplified)
data class QueueMenuSetting(
    val sdk: QueueMenuSDKSetting?
    // ... other fields ...
)

data class QueueMenuSDKSetting(
    val preSessionSmartAction: Boolean?
    // ... other fields ...
)

// Usage - "does any queue-level setting require a pre-session smart action?"
fun queueRequiresPreSession(menu: QueueMenu): Boolean {
    return menu.settings?.any { it.sdk?.preSessionSmartAction == true } ?: false
}

Ruta B: A nivel del canal (VoiceCallChannel.preSessionSmartAction)

// Usage - "does the voice channel specifically require pre-session capture?"
val requiresPreSessionOnVoice =
    menu.channels.voiceCall?.preSessionSmartAction == true

Usa la ruta A para decidir si se muestra una puerta previa a la sesión antes de que el usuario elija un canal. Usa la ruta B para los ajustes específicos del canal después de seleccionar un canal (por ejemplo, solo solicitar antes de una llamada de voz instantánea).

Acciones inteligentes durante la sesión (iniciadas por el agente)

Durante un chat o una llamada de voz activos, un agente puede hacer clic en un botón de su panel para solicitar datos al usuario (por ejemplo, Envía una foto de tu documento de identidad o Autentícate con datos biométricos).

Qué proporciona el SDK: Eventos en tiempo real que alertan a tu app de que el agente solicitó un tipo específico de acción inteligente.

Lo que compilarás: Una alerta en el chat o en la llamada que notifique al usuario sobre la solicitud, inicie la herramienta integrada adecuada (cámara, biblioteca de fotos, campo de texto o BiometricPrompt de Android) y pase el resultado al SDK.

Ejemplo de implementación

Aquí, tu app escucha los eventos del SDK. Cuando detecta una solicitud del agente, muestra una alerta y, luego, abre la herramienta de Android correspondiente.

import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat

// Listen for Smart Action requests from the active SDK session.
//
// `SmartActionRequest` exposes a nested `smartAction: SmartAction`, and the
// switchable type lives at `request.smartAction.type`. The `SmartActionType`
// enum is `PascalCase: Unknown`, `Verification`, `Screenshot`, `Photo`, `Video`,
// `TextInput`, `ScreenShare`. Use `Verification` for Face ID / fingerprint flows.
fun handleSmartActionRequest(request: SmartActionRequest) {
    when (request.smartAction.type) {
        SmartActionType.Photo -> {
            promptUserForPhoto(message = "The agent requested a photo.") { capturedBitmap ->
                // Send the image back to the agent using the SDK.
                sendAttachment(image = capturedBitmap)
            }
        }

        SmartActionType.Verification -> {
            val executor = ContextCompat.getMainExecutor(this)
            val biometricPrompt = BiometricPrompt(this, executor,
                object : BiometricPrompt.AuthenticationCallback() {
                    override fun onAuthenticationSucceeded(
                        result: BiometricPrompt.AuthenticationResult
                    ) {
                        sendBiometricResult(success = true)
                    }

                    override fun onAuthenticationFailed() {
                        sendBiometricResult(success = false)
                    }

                    override fun onAuthenticationError(
                        errorCode: Int, errString: CharSequence
                    ) {
                        sendBiometricResult(success = false)
                    }
                }
            )

            val promptInfo = BiometricPrompt.PromptInfo.Builder()
                .setTitle("Identity Verification")
                .setSubtitle("Verify your identity to continue")
                .setNegativeBtnText("Cancel")
                .build()

            biometricPrompt.authenticate(promptInfo)
        }

        SmartActionType.TextInput -> {
            presentTextInputPrompt(message = "The agent requested text input.") { text ->
                sendSmartActionText(text)
            }
        }

        SmartActionType.Video -> {
            // Agent-requested video capture. Reuse the same disk-cached file
            // pattern recommended for pre-session media keep the recording on
            // disk and pass the local Uri to the SDK rather than holding a
            // large `ByteArray` in memory.
            promptUserForVideo(message = "The agent requested a video.") { capturedVideoUri ->
                sendAttachment(videoUri = capturedVideoUri)
            }
        }

        SmartActionType.Screenshot -> {
            // The SDK exposes `Screenshot` as a distinct request type the
            // user captures (or selects), a single still image of the current
            // screen. This is **not** the same as `ScreenShare`, which
            // starts a live co-browse session.
            promptUserForScreenshot(message = "The agent requested a screenshot.") { capturedBitmap ->
                sendAttachment(image = capturedBitmap)
            }
        }

        SmartActionType.ScreenShare -> {
            // Hand off to the full screen share flow (see Headless Mobile SDK for Android: Voice, screen share, scheduled call, and email).
            // Don't confuse with `Screenshot`;  `ScreenShare` starts a
            // live co-browse session using `CCAIScreenShare`, while `Screenshot`
            // captures a single still frame.
            startScreenShareFlow()
        }

        SmartActionType.Unknown -> {
            // Future-proof: a smart action type the SDK does not recognize.
            // Log and continue; don't block the user.
            Log.w("CCAI", "Received unknown smart action type")
        }
    }
}

Las acciones inteligentes iniciadas por el agente llegan a través de los eventos del SDK de la sesión activa. Suscríbete a los eventos de chat o llamada pertinentes antes de iniciar la sesión para que tu app pueda presentar el mensaje adecuado para el cliente en cuanto llegue una solicitud.

Notifica y realiza un seguimiento de las acciones inteligentes

Usa smartActionService para confirmar y actualizar las acciones inteligentes a medida que el usuario avanza en ellas.

val router = CommunicationRouter(
    id = chatId,
    type = CommunicationType.Chat
)

// Notify the server that a smart action has been received.
lifecycleScope.launch {
    try {
        CCAI.smartActionService?.notifySmartActionReceived(
            router = router,
            smartActionId = smartActionId
        )
        Log.d("CCAI", "Smart action notification sent successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to notify smart action: ${e.message}")
    }
}

// Update the smart action status as the user completes it.
lifecycleScope.launch {
    try {
        CCAI.smartActionService?.updateSmartActionStatus(
            router = router,
            smartActionId = smartActionId,
            status = SmartActionStatus.Finished
        )
        Log.d("CCAI", "Smart action status updated successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to update smart action status: ${e.message}")
    }
}

Si la acción solicita entrada de texto, recopila el texto en tu IU y envíalo a través del servicio de acción inteligente antes de marcar la acción como finalizada.

Formularios web

Qué proporciona el SDK: APIs para recuperar, mostrar y validar formularios web activados por agentes durante una sesión de chat.

Lo que compilarás: La IU de renderización del formulario web y el flujo de envío que empaqueta las respuestas del usuario.

Ejemplo de implementación

Este código recupera un formulario web por su ID externo y su ID de acción inteligente, y, luego, valida la respuesta antes del envío.

// Fetch a web form - `fetchWebForm` takes two positional parameters on Android.
lifecycleScope.launch {
    try {
        val webFormResponse = CCAI.chatService?.fetchWebForm(
            externalFormId = "form123",
            smartActionId = 123
        )
        if (webFormResponse != null) {
            Log.d("CCAI", "Web form received: $webFormResponse")
            // Render the web form in your custom UI.
            renderWebForm(webFormResponse)
        }
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to fetch web form: ${e.message}")
    }
}

// Validate a web form response.
lifecycleScope.launch {
    try {
        val isValid = CCAI.chatService?.validateWebForm(webFormResponse)
        if (isValid == true) {
            Log.d("CCAI", "Web form is valid")
        } else {
            Log.d("CCAI", "Web form validation failed")
        }
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to validate web form: ${e.message}")
    }
}

Formularios personalizados

Qué proporciona el SDK: APIs para recuperar definiciones de formularios configurables (con varios tipos de preguntas) y enviar las respuestas del usuario.

Lo que crearás: Una IU de formulario dinámica que renderiza cada tipo de pregunta (campos de texto, menús desplegables, etc.), valida la entrada y recopila respuestas para el envío.

Ejemplo de implementación

Este código recupera las definiciones de las preguntas de un formulario personalizado y, luego, empaqueta y envía las respuestas del usuario.

// Retrieve custom form details
lifecycleScope.launch {
    try {
        val formDetails = CCAI.chatService?.getCustomFormDetails(formId = 123)
        if (formDetails != null) {
            Log.d("CCAI", "Form Title: ${formDetails.title ?: "No title"}")
            Log.d("CCAI", "Questions: ${formDetails.questions.size}")
            // Render the form dynamically based on question types
            renderCustomForm(formDetails)
        }
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to get custom form details: ${e.message}")
    }
}

// Submit a custom form
val request = SubmitCustomFormRequest(
    smartActionId = 123,
    formResponse = listOf(
        SubmitCustomFormRequest.Answer(questionId = 1, value = "John Doe"),
        SubmitCustomFormRequest.Answer(questionId = 2, value = "john@example.com")
    )
)

lifecycleScope.launch {
    try {
        CCAI.chatService?.submitCustomForm(request = request)
        Log.d("CCAI", "Form submitted successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to submit form: ${e.message}")
    }
}

Para ver las definiciones completas de las enumeraciones CustomFormDetailsResponse, CustomFormQuestion, CustomFormQuestionOption y CustomFormQuestionType, consulta la Referencia de la API del SDK para dispositivos móviles sin interfaz gráfica de Android.

Archivos adjuntos iniciados por el consumidor (chat)

Los usuarios no tienen que esperar a que un agente les pregunte, sino que pueden enviar imágenes y videos de forma proactiva durante un chat. El SDK aplica límites estrictos de tamaño de archivo y automáticamente intenta la compresión antes de la transmisión.

Límites de tamaño de los archivos adjuntos

  • Imágenes: ≤ 2 MB

  • Videos: ≤ 20 MB

Qué proporciona el SDK: Una canalización de carga segura que controla la transmisión de red y comprime automáticamente los archivos para cumplir con los límites de la plataforma de CCAI.

Lo que compilas: El botón de clip/adjunto en la IU del chat, el selector de fotos o videos, y la burbuja de chat visual que muestra el estado de carga (cargando, enviado o fallido).

Ejemplo de implementación

Cuando un usuario selecciona una foto o un video de su galería, pasa el archivo local Uri al SDK con la misma API de sendMessage que se usa para todos los mensajes salientes. Para obtener más información, consulta Cómo enviar mensajes.

El SDK controla la compresión y la carga.

// Called when the user picks an image from their photo gallery
fun userDidSelectImage(imageUri: Uri) {
    val messageBubble = myChatAdapter.addLoadingImageBubble()

    lifecycleScope.launch {
        try {
            CCAI.chatService?.sendMessage(
                OutgoingMessageContent.Photos(
                    images = listOf(imageUri),
                    smartAction = null
                )
            )
            messageBubble.markAsSent()
        } catch (e: Exception) {
            messageBubble.showError("Failed to send: ${e.message}")
        }
    }
}

Archivos adjuntos iniciados por el agente (chat)

Los agentes pueden enviar archivos al usuario, incluidas imágenes, videos, clips de audio y documentos (PDFs, CSVs, etcétera).

Tipos de archivos admitidos

La plataforma de CCAI acepta 19 tipos de archivos en cuatro categorías. Tu IU personalizada debe controlar cada categoría de forma correcta (vista previa de imágenes, reproductor de video, reproductor de audio, descarga de documentos).

Categoría Tipos compatibles
Imágenes JPEG, PNG, GIF y WebP
Video MP4, MOV, AVI, WMV y WebM
Audio MP3, WAV, M4A y WEBA.
Documentos PDF, DOC, XLS, PPT, CSV y TXT

Qué proporciona el SDK: Cargas útiles de mensajes de chat entrantes que se entregan con el mensaje Flow del servicio de chat que incluye metadatos de archivos adjuntos. Consulta SDK de Headless para dispositivos móviles de Android: Temas avanzados, localización y flujos posteriores a la sesión. El servicio de chat también proporciona downloadMedia para recuperar de forma segura el contenido multimedia enviado por el agente.

Qué compilarás: La IU para renderizar estos adjuntos en el feed de chat. Tu app decide si mostrar vistas previas de imágenes, miniaturas de videos, controles de reproducción de audio o botones de descarga de documentos.

Ejemplo de implementación

Observa los mensajes entrantes con el mensaje Flow del servicio de chat. Cuando un mensaje nuevo incluye metadatos de contenido multimedia, llama a downloadMedia antes de renderizar o abrir el archivo.

downloadMedia devuelve DownloadMediaResponse { data: ByteArray, fileName: String? }, es decir, los bytes descargados por completo más un nombre de archivo para mostrar opcional. El SDK no almacena en caché las descargas. Si la IU se desplaza hacia atrás a una burbuja anterior o vuelve a ingresar a la vista de chat, tu app es responsable de almacenar en caché la imagen decodificada o conservar los bytes. Si vuelves a llamar a downloadMedia, se activará otra recuperación de red.

import android.graphics.BitmapFactory
import java.io.File

lifecycleScope.launch {
    CCAI.chatService?.messagesReceived?.collect { messages ->
        for (message in messages) {
            renderIncomingMessage(message)
        }
    }
}

fun renderIncomingMessage(message: ChatMessage) {
    val media = message.media

    if (media == null) {
        myChatAdapter.insertTextBubble(text = message.text)
        return
    }

    lifecycleScope.launch {
        try {
            // `downloadMedia` returns the raw bytes plus an optional filename.
            val response = CCAI.chatService?.downloadMedia(
                mediaId = media.id,
                mediaType = media.type
            ) ?: return@launch

            when (media.type) {
                DownloadableMediaType.Photo -> {
                    // Decode in-memory; no disk write needed.
                    val bitmap = BitmapFactory.decodeByteArray(
                        response.data, 0, response.data.size
                    )
                    myChatAdapter.insertImageBubble(
                        bitmap = bitmap,
                        fileName = response.fileName
                    )
                }
                DownloadableMediaType.Video,
                DownloadableMediaType.Audio,
                DownloadableMediaType.Document -> {
                    // Larger media usually needs an on-disk file for a player
                    // or document viewer. Write to the app's cache directory
                    // yourself and hand the resulting File/Uri to your UI.
                    val file = File(
                        applicationContext.cacheDir,
                        response.fileName ?: "attachment"
                    )
                    file.writeBytes(response.data)
                    myChatAdapter.insertAttachmentBubble(
                        file = file,
                        mediaType = media.type
                    )
                }
            }
        } catch (e: Exception) {
            myChatAdapter.insertAttachmentErrorBubble(fileName = message.media?.name)
        }
    }
}

Desvío (fuera de horario y por capacidad excedida)

La desviación redirecciona a los usuarios cuando tu equipo de asistencia no está disponible. Esto suele ocurrir en dos situaciones:

  • Fuera de horario: El usuario intenta comunicarse con el equipo de asistencia fuera del horario de atención al cliente configurado.

  • Sobre capacidad: La fila está abierta, pero el tiempo de espera supera el umbral configurado por el administrador.

En una arquitectura sin interfaz gráfica, el SDK no bloquea automáticamente al usuario ni muestra una pantalla de error. En cambio, pasa de forma silenciosa el estado de redireccionamiento y las opciones de resguardo configuradas por el administrador a tu app. Tu app debe verificar este estado antes de intentar iniciar una sesión.

Cómo controlar los estados de desvío

Qué proporciona el SDK: Un deflectionFrom: List<QueueMenuDeflection>? en QueueMenu que enumera las reglas de desvío entrantes que enrutan otras colas a esta. Cada QueueMenuDeflection solo contiene dos campos:

  • deflectionType: DeflectionType?: Es la categoría de desvío (por ejemplo, fuera de horario o sobrecarga).

  • menuId: Int?: Es el ID de la cola de origen que se desvía a esta.

QueueMenuDeflection no incluye un mensaje visible ni una etiqueta legible para las personas. Para el texto visible para el usuario (por ejemplo, Nuestra oficina está cerrada),usa afterHoursMessage de la cola (derivado de QueueMenu.settings[].afterHours) o tus propias cadenas configuradas por el administrador. Para el nombre visible de la fila de destino resuelta, búscalo en el árbol de menú que ya recuperaste con menuId.

Lo que compilas: La lógica para verificar estos estados de desvío antes de poner a un usuario en una fila y la IU personalizada (como una alerta de pantalla completa o un banner) que muestra el mensaje adecuado y los botones de redireccionamiento alternativos.

Ejemplo de implementación

El siguiente código intercepta el intento de un usuario de iniciar un chat. Verifica los metadatos de desvío del SDK en QueueMenu y, si hay una regla activa, presenta una pantalla de desvío con el afterHoursMessage de la fila (o un elemento de resguardo).

fun onSupportMenuTapped(queueMenu: QueueMenu) {
    // 1. Check if any deflection rules route into this queue.
    val deflections = queueMenu.deflectionFrom
    if (!deflections.isNullOrEmpty()) {
        // Deflection is active - stop routing. Show the custom deflection screen instead.
        val message = queueMenu.afterHoursMessage?.text
            ?: "Support is currently unavailable."
        showDeflectionScreen(
            message = message,
            deflections = deflections
        )
    } else {
        // No deflection rules apply. Safe to proceed to channel selection or directly to chat/call.
        startSupportFlow(queueMenu)
    }
}

Opciones de desvío de renderización

Cuando una regla de desvío está activa, es probable que tus administradores configuren formas alternativas para que el usuario obtenga ayuda, por lo general, indicando otra cola (que puedes resolver con menuId) o mostrando el afterHoursMessage configurado de la cola actual.

Qué proporciona el SDK: La lista de entradas QueueMenuDeflection en deflectionFrom, cada una con un deflectionType y un menuId.

Lo que compilarás: Un menú dinámico que itera a través de estas entradas, resuelve cada menuId en tu árbol de menú ya recuperado para obtener un nombre visible y genera los botones adecuados.

Ejemplo de implementación

Este código toma las entradas de desvío y compila una pantalla de forma dinámica. Usa el nombre de la fila de origen (que se resuelve a partir de menuId) como etiqueta del botón y recurre a deflectionType cuando no hay un nombre disponible.

fun showDeflectionScreen(message: String, deflections: List<QueueMenuDeflection>) {
    // 1. Update your UI with the admin's configured message (or your fallback).
    deflectionTitleTextView.text = message

    // 2. Loop through the incoming deflection rules and generate buttons.
    for (deflection in deflections) {
        val sourceMenu = deflection.menuId?.let { findMenuById(it) }
        val label = sourceMenu?.name
            ?: deflection.deflectionType?.name
            ?: "Alternative option"

        val button = MaterialButton(this).apply {
            text = label
            setOnClickListener {
                handleDeflectionAction(deflection)
            }
        }
        menuLinearLayout.addView(button)
    }

    // 3. Present the compiled screen to the user.
    deflectionContainer.isVisible = true
}

// Walk your previously fetched menu tree (for example, by using `QueueMenu.flatten()`) to resolve a `menuId`.
private fun findMenuById(id: Int): QueueMenu? =
    cachedRootMenus.flatMap { it.flatten() }.firstOrNull { it.id == id }

deflectionFrom es la lista de reglas de desvío que enrutan a este menú. El menuId de cada entrada identifica una cola de origen que desvía a la actual. Tu app decide cómo exponerlos. Algunas integraciones presentan la fila de destino como aquí es donde te enviaremos, mientras que otras solo usan la presencia de cualquier regla como puerta para mostrar una pantalla genérica de inténtalo de nuevo más tarde.