SDK mobile headless pour Android : files d'attente, canaux et chat

Ce document explique comment rendre les points d'entrée d'assistance (files d'attente et canaux) disponibles dans votre application, et comment gérer l'intégralité du cycle de vie du chat : démarrage, reprise, envoi de messages et de pièces jointes, indication de saisie, masquage des données sensibles, transfert à des agents humains et fin de la session.

Avant de commencer

Configurez le SDK. Pour en savoir plus, consultez SDK mobile headless pour Android : premiers pas.

Sélectionner des files d'attente et des canaux

  • Une file d'attente représente généralement un point d'entrée d'assistance, tel que "Facturation", "Assistance technique" ou "Assistance VIP".

  • Chaque file d'attente peut proposer un ou plusieurs des canaux suivants :

    • Chat

    • Appel instantané (vocal)

    • Appel planifié

    • E-mail

    • Liens de déviation externe (liens vers vos pages en libre-service ou d'autres canaux)

Les files d'attente et la disponibilité des canaux sont configurées par les administrateurs dans le portail d'administration de Contact Center AI Platform.

Présentation dans votre application

Dans votre application, le parcours est généralement le suivant :

  1. Vous ajoutez un point d'entrée d'assistance dans votre application (par exemple, un onglet Aide ou un bouton Nous contacter).

  2. Lorsque l'utilisateur appuie dessus, vous récupérez le menu de la file d'attente à l'aide du SDK et affichez votre propre UI de menu.

  3. Lorsque l'utilisateur choisit une file d'attente, vous inspectez ses canaux disponibles.

  4. Votre application présente ces canaux à l'utilisateur (par exemple, Discuter maintenant, Appeler maintenant, Planifier un appel, Nous envoyer un e-mail, Accéder au centre d'aide).

  5. Lorsque l'utilisateur sélectionne un canal, vous appelez l'API SDK correspondante.

Récupérer les menus de la file d'attente à partir du SDK

Le SDK fournit queueMenuService pour récupérer les menus de file d'attente. La méthode get renvoie un QueueMenuResult contenant la liste des files d'attente (List<QueueMenu>) et un indicateur isDirectAccess. Vous pouvez soit récupérer l'arborescence complète du menu, soit utiliser une clé d'accès direct pour accéder directement à une file d'attente spécifique :

import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaikit.models.response.queuemenu.QueueMenuResult
import com.ccaiplatform.ccaikit.models.response.queuemenu.QueueMenu

// Fetch the full queue menu tree
val menuResult: QueueMenuResult? = CCAI.queueMenuService?.get()

// Or fetch a specific queue using a Direct Access Key
val menuResult: QueueMenuResult? = CCAI.queueMenuService?.get(key = "billing_vip")

Le paramètre facultatif key vous permet de contourner le menu de la file d'attente complète et de rediriger l'utilisateur directement vers une file d'attente spécifique. Dans CCAI Platform, cela est possible grâce à un point d'accès direct (DAP).

Les administrateurs peuvent configurer un DAP dans le portail CCAI Platform de la manière suivante :

  1. Accédez à Paramètres > File d'attente > sélectionnez une file d'attente dans la structure du menu.

  2. Dans la section Point d'accès, cliquez sur + Créer un point d'accès direct.

  3. Saisissez la clé dans le formulaire de texte.

  4. Cliquez sur Enregistrer.

Structure de données QueueMenu

Chaque QueueMenu contient :

Propriété Type Description
id Int Identifiant unique de cette file d'attente.
name String? Nom à afficher (par exemple, "Assistance facturation").
children List<QueueMenu> Sous-menus (liste vide s'il s'agit d'un nœud feuille).
channels Chaînes ? Canaux disponibles pour cette file d'attente.
hidden Booléen Indique si cette file d'attente doit être masquée pour les clients (configuré par l'administrateur).
position Int? Position d'affichage définie par le serveur : conserve l'ordre du portail d'administration.
settings List<QueueMenuSetting>? Paramètres au niveau de la file d'attente configurés dans le portail administrateur.
redirectionExtra QueueMenuRedirection? Métadonnées de redirection automatique lorsqu'elles sont configurées (voir Redirection et déviation)
deflectionFrom List<QueueMenuDeflection>? Files d'attente qui ont été redirigées vers celle-ci. La plate-forme renvoie cette file d'attente à la place. Une liste non vide explique donc une redirection qui a déjà eu lieu (voir Déviation).

La classe de données Channels possède les propriétés suivantes :

Propriété Type Description
chat ChatChannel? Configuration du canal de chat (null si le chat n'est pas disponible pour cette file d'attente).
voiceCall VoiceCallChannel? Configuration du canal d'appel vocal (null si la voix n'est pas disponible). Contient des indicateurs tels que scheduleEnabled et les préférences d'enregistrement.
email EmailChannel? Configuration du canal de messagerie (null si l'adresse e-mail n'est pas disponible). Accédez à l'adresse à l'aide de channels.email?.email.
externalDeflectionLink ExternalDeflectionLink? Configuration du lien de déviation externe (null si non disponible). Accédez à l'URL à l'aide des propriétés du type structuré.

Champs VoiceCallChannel (métadonnées de capacité et de déviation)

// VoiceCallChannel.kt (simplified)
data class VoiceCallChannel(
    val instantEnabled: Boolean,            // Live voice call allowed now
    val preSessionSmartAction: Boolean,     // Per-channel pre-session smart action flag
    val scheduleEnabled: Boolean,           // Scheduled calls supported
    val recordingOption: RecordingOption?,  // ALWAYS / NEVER / ASK_USER
    val voicemailReason: String?,
    val phoneNumber: String?,
    val scheduleDeflectionType: String?,
    val deflected: Boolean?,
    val deflectedReason: String?
)

Exemple de mise en œuvre

fun showAvailableChannels(queueMenu: QueueMenu) {
    val channels = queueMenu.channels

    val voice = channels?.voiceCall

    // Show only what the platform enabled, and hide everything else so
    // nothing carries over from a previously selected queue
    chatButton.isVisible = channels?.chat?.enabled == true
    callButton.isVisible = voice != null && voice.instantEnabled && !voice.deflected
    scheduleButton.isVisible = voice?.scheduleEnabled == true
    emailButton.isVisible = channels?.email?.enabled == true

    // External deflection links: the enabled entries that have a URL
    val links = channels?.externalDeflectionLink
        ?.takeIf { it.enabled }
        ?.links.orEmpty()
        .filter { it.enabled && it.url != null }
    helpLinksButton.isVisible = links.isNotEmpty()
}

Récupération des temps d'attente…

Vous pouvez également récupérer les temps d'attente estimés pour une file d'attente spécifique :

// Fetch wait time for a specific queue
val waitTime = CCAI.queueMenuService?.getWaitTimes(menuId = queueMenu.id)

// waitTime contains:
// - chat: estimated wait time for chat (in seconds)
// - voiceCall: estimated wait time for voice call (in seconds)

Files d'attente à canal unique

Si une file d'attente ne propose qu'un seul canal (par exemple, l'e-mail uniquement), vous pouvez :

  • Ignorer l'étape de sélection du canal et accéder directement à l'interface utilisateur appropriée.

  • Vous pouvez également afficher explicitement le canal disponible si cela est plus pertinent pour votre UX.

La configuration et les métadonnées du SDK vous indiquent les canaux autorisés. Votre application décide comment les afficher.

Redirection et déviation

Les administrateurs peuvent configurer une file d'attente pour rediriger les utilisateurs au lieu de proposer des canaux. Lorsque QueueMenu.redirectionExtra est défini, agissez dès que l'utilisateur sélectionne la file d'attente :

  • option indique l'action à effectuer : PHONE, MESSAGE, URL, VOICEMAIL, QUEUE, SIP ou CONTACT.
  • data contient la valeur, par exemple le numéro à composer, le message à afficher ou l'URL à ouvrir.

QueueMenu.deflectionFrom est différent. Lorsqu'une file d'attente est redirigée vers une autre, la plate-forme renvoie la file d'attente de destination à la place de celle sélectionnée par l'utilisateur et liste les files d'attente sources dans deflectionFrom. Il explique une redirection qui a déjà eu lieu. Il ne s'agit pas d'un ensemble d'options à proposer.

La déviation en dehors des heures de travail et en cas de dépassement de capacité est signalée par canal. Pour savoir comment gérer ce problème, consultez SDK mobile sans interface graphique pour Android : actions intelligentes, pièces jointes et déviation.

Canaux

Dans le SDK mobile sans interface graphique, le portail d'administration de CCAI Platform sert de source de vérité pour vos opérations d'assistance. Les administrateurs configurent les canaux d'assistance (tels que le chat, la voix, l'e-mail ou les liens utiles) disponibles pour différentes files d'attente d'assistance (telles que "Facturation" ou "Assistance technique").

Le SDK est chargé de récupérer cette configuration de manière sécurisée et de la transmettre à votre application. Votre application est chargée de lire cette configuration et de dessiner l'interface utilisateur appropriée.

Inspecter les canaux disponibles

Ce que fournit le SDK : un instantané en temps réel des canaux d'assistance actifs et disponibles pour la file d'attente spécifique sélectionnée par l'utilisateur, en respectant les horaires d'ouverture et les limites de capacité de votre portail.

Ce que vous créez : le menu de l'interface utilisateur (boutons, listes ou fiches) qui affiche ces options disponibles pour l'utilisateur.

Exemple d'implémentation : le code Kotlin suivant prend la file d'attente sur laquelle l'utilisateur vient d'appuyer et inspecte la classe de données Channels pour voir quels canaux sont activés. Il décide ensuite des boutons à afficher à l'écran.

// Assuming 'selectedMenu' is a QueueMenu returned by the SDK
fun setupChannelMenu(selectedMenu: QueueMenu) {
    val channels = selectedMenu.channels

    if (channels.chat != null) {
        showChatNowButton()
    }

    if (channels.voiceCall != null) {
        showCallNowButton()
    }

    if (channels.email != null) {
        showEmailUsButton()
    }

    if (channels.externalDeflectionLink != null) {
        showHelpCenterLinks()
    }
}

Les sections suivantes décrivent le chat en détail. Pour les appels vocaux, le partage d'écran, les appels programmés, les e-mails et les liens de redirection externe, consultez SDK mobile headless pour Android : appels vocaux, partage d'écran, appels programmés et e-mails.

API du service Chat

chatService gère l'intégralité du cycle de vie du chat. Les méthodes principales que vous utilisez le plus fréquemment sont les suivantes :

Méthode Description
start Démarre une nouvelle session de chat avec un ChatRequest.
sendMessage Envoie un message (texte, image, vidéo ou événement de formulaire).
typing Met à jour l'indicateur de saisie.
endChat Met fin à la session de chat en cours.
resumeChat Reprend une session de chat précédemment établie.
escalateToHumanAgent Transferts d'un agent virtuel vers un agent humain.
checkStatus Actualise l'état actuel du chat à partir du serveur.

Structures de données ChatRequest et ChatResponse

La classe de données ChatRequest contient la configuration permettant de démarrer une nouvelle discussion :

data class ChatRequest(
    val chat: Chat? = null,                 // The session configuration (always pass one)
    val isScreenShareable: Boolean? = null, // Optional: enable screen share for this session
    val isVerifiable: Boolean? = null       // Optional: allow verification smart actions
)

data class Chat(
    val menuId: Int,                    // Required: queue menu ID
    val lang: String? = "en",           // Optional: language code override (defaults to "en")
    val ticketId: String? = null,       // Optional: associate with existing ticket
    val greeting: String? = null,       // Optional: custom greeting message
    val customData: CustomData? = null, // Optional: structured custom data
    val displayOrderInAdapter: List<String>? = null,
    val directAccessKeyId: Int? = null, // Optional: from QueueMenuResult (Direct Access Point)
    val dapRequestId: String? = null    // Optional: from QueueMenuResult (Direct Access Point)
)

Une fois que vous avez démarré ou repris une discussion, le SDK envoie son ChatResponse sur le flux chatReceived (start() et resumeChat() ne renvoient rien). Les propriétés auxquelles vous ferez le plus référence dans ce guide sont les suivantes :

  • id : identifiant unique de la session de chat.

  • status : état actuel du chat (en attente, actif, terminé, etc.).

  • agent / virtualAgent : l'agent humain ou virtuel attribué.

  • postSessionRequired : indique si un agent virtuel post-session est configuré pour la session. Les enquêtes et le CSAT sont signalés par surveyEnabled et csatSetting.

  • redactionEnabled : indique si la suppression automatique des informations permettant d'identifier personnellement l'utilisateur est active pour cette session.

Démarrer une session de chat

Pour démarrer une session de chat, utilisez chatService avec un ChatRequest spécifiant l'ID du menu de la file d'attente.

Exemple minimal

import android.util.Log
import androidx.lifecycle.lifecycleScope
import com.ccaiplatform.ccaichat.chatService
import com.ccaiplatform.ccaichat.model.Chat
import com.ccaiplatform.ccaichat.model.ChatRequest
import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaiscreenshare.screenShareService
import kotlinx.coroutines.launch

// If screen share is initialized, pass isScreenShareable for agent visibility
val chatRequest = ChatRequest(
    chat = Chat(menuId = 123),
    isScreenShareable = CCAI.screenShareService != null
)
startOrResumeChat(chatRequest)

// Resumes an earlier chat if there is one; otherwise starts a new one
fun startOrResumeChat(chatRequest: ChatRequest) {
    lifecycleScope.launch {
        val chatService = CCAI.chatService ?: return@launch
        try {
            // Pre-flight check: resume an earlier chat instead of starting a second one
            val existing = chatService.getLastChatInProgress()
            if (existing != null) {
                chatService.resumeChat(existing)
                return@launch
            }

            chatService.start(chatRequest)
            // Chat started - navigate to your custom chat screen
        } catch (e: Exception) {
            Log.e("CCAI", "Failed to start chat: ${e.message}")
        }
    }
}

Si votre application n'inclut pas le module CCAIScreenShare, supprimez l'importation screenShareService et l'argument isScreenShareable.

Avec des propos explicites

val chatRequest = ChatRequest(
    chat = Chat(menuId = 123, lang = "en")
)
startOrResumeChat(chatRequest) // Defined in the Minimal example

Reprendre une session de chat

Reprenez une session de chat précédemment établie à l'aide d'un objet ChatResponse :

lifecycleScope.launch {
    try {
        CCAI.chatService?.resumeChat(chat)
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to resume chat: ${e.message}")
    }
}

Gestion de la file d'attente de chat

Vous pouvez remettre le chat actuel dans la file d'attente (son état devient "en file d'attente") ou rechercher des chats en cours :

// Enqueue the current chat (automatically calls checkStatus() after enqueuing)
lifecycleScope.launch {
    try {
        CCAI.chatService?.enqueueCurrentChat()
        Log.d("CCAI", "Chat enqueued successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to enqueue chat: ${e.message}")
    }
}

// Check for an existing in-progress chat
lifecycleScope.launch {
    try {
        val chat = CCAI.chatService?.getLastChatInProgress()
        if (chat != null) {
            Log.d("CCAI", "Found ongoing chat: ${chat.id}")
        } else {
            Log.d("CCAI", "No ongoing chat found")
        }
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to get last chat: ${e.message}")
    }
}

// Retrieve previous chat history with pagination
lifecycleScope.launch {
    try {
        val previousChats = CCAI.chatService?.getPreviousChats(currentPage = 1)
        if (previousChats != null) {
            Log.d("CCAI", "Found ${previousChats.messages.size} previous messages")
        }
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to get previous chats: ${e.message}")
    }
}

Envoyer des messages

La méthode sendMessage accepte plusieurs types de messages via la classe scellée OutgoingMessageContent :

sealed class OutgoingMessageContent {
    data class Text(val content: String) : OutgoingMessageContent()
    data class Photos(
        val images: List<UploadableImage>,
        val smartAction: SmartAction? = null
    ) : OutgoingMessageContent()
    data class Videos(
        val video: UploadableVideo,
        val smartAction: SmartAction? = null
    ) : OutgoingMessageContent()
    data class FormComplete(
        val type: String? = null,
        val signature: String? = null,
        val data: FormCompleteEventData
    ) : OutgoingMessageContent()
    data class ScreenShare(
        val event: String,
        val detail: ScreenShareResponse? = null
    ) : OutgoingMessageContent()
}

Les types UploadableImage et UploadableVideo (dans com.ccaiplatform.ccaikit.models.smartaction) encapsulent les contenus multimédias à importer :

data class UploadableImage(
    val data: ByteArray,       // The binary data of the image
    val mimeType: String,      // For example, "image/jpeg" or "image/png"
    val uri: Uri? = null       // Optional URI for display and local file reference
)

data class UploadableVideo(
    val uri: Uri,              // The file URI of the video
    val mimeType: String       // For example, "video/mp4"
)

Photos accepte une liste d'images, tandis que Videos accepte une seule vidéo. Évitez de conserver des éléments multimédias volumineux en mémoire pendant que l'utilisateur attend dans la file d'attente ou qu'une importation est en attente.

Exemples d'utilisation

// Send text message
lifecycleScope.launch {
    try {
        CCAI.chatService?.sendMessage(OutgoingMessageContent.Text("Hello world"))
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send message: ${e.message}")
    }
}

// Send image message (read the file off the main thread)
lifecycleScope.launch {
    try {
        val imageData = withContext(Dispatchers.IO) {
            requireNotNull(contentResolver.openInputStream(selectedImageUri)).use { it.readBytes() }
        }
        val images = listOf(
            UploadableImage(data = imageData, mimeType = "image/jpeg", uri = selectedImageUri)
        )
        CCAI.chatService?.sendMessage(
            OutgoingMessageContent.Photos(
                images = images,
                smartAction = null
            )
        )
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send image: ${e.message}")
    }
}

// Send video message (one video per message)
val video = UploadableVideo(uri = selectedVideoUri, mimeType = "video/mp4")

lifecycleScope.launch {
    try {
        CCAI.chatService?.sendMessage(
            OutgoingMessageContent.Videos(
                video = video,
                smartAction = null
            )
        )
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send video: ${e.message}")
    }
}

// Send form completion event
// Note: status is a nullable String: "success", "error", or "cancelled".
val formCompleteData = FormCompleteEventData(
    smartActionId = 123,
    status = "success",
    timestamp = "2024-01-01T12:00:00Z",
    details = FormCompleteEventDetails(message = "Form submitted successfully")
)

lifecycleScope.launch {
    try {
        CCAI.chatService?.sendMessage(
            OutgoingMessageContent.FormComplete(data = formCompleteData)
        )
        Log.d("CCAI", "Form completion event sent")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send form completion: ${e.message}")
    }
}

Le type de message ScreenShare permet d'envoyer des événements et des réponses de partage d'écran au serveur. Les événements de partage d'écran disponibles sont les suivants :

  • screenShareRequestedFromAgent - L'agent a demandé le partage d'écran

  • screenShareRequestedFromEndUser : l'utilisateur final a demandé le partage d'écran

  • screenShareCodeGenerated : un code de partage d'écran a été généré

  • screenShareFailed - screen sharing failed

  • screenShareStarted - Session de partage d'écran démarrée

  • screenShareEnded - session de partage d'écran terminée

Indicateurs de saisie et aperçus des messages

Mettez à jour l'état de saisie et envoyez des aperçus de messages pendant que l'utilisateur tape :

// Update typing indicator
CCAI.chatService?.typing(true)   // Start typing
CCAI.chatService?.typing(false)  // Stop typing

// Send message preview
lifecycleScope.launch {
    try {
        CCAI.chatService?.sendMessagePreview("Typing...")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send message preview: ${e.message}")
    }
}

// Example: Send preview as user types
fun onTextChanged(text: String) {
    lifecycleScope.launch {
        try {
            CCAI.chatService?.sendMessagePreview(text)
        } catch (e: Exception) {
            Log.e("CCAI", "Failed to send preview: ${e.message}")
        }
    }
}

Masquage des messages

La suppression automatique des informations sensibles (informations permettant d'identifier personnellement l'utilisateur, numéros de carte de crédit, etc.) est possible pour les messages de chat en texte brut et les aperçus de messages.

Configuration du masquage :

  • Contrôlé par la propriété redactionEnabled dans ChatResponse.

  • Configuré dans le portail sous Paramètres > Paramètres de chat > Masquage automatique.

  • Lorsqu'elle est activée, les données sensibles sont automatiquement remplacées par des espaces réservés avant d'être envoyées aux agents.

// Redaction is automatically handled, use sendMessage as usual
lifecycleScope.launch {
    try {
        CCAI.chatService?.sendMessage(
            OutgoingMessageContent.Text("My phone number is 4155553423")
        )
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send message: ${e.message}")
    }
}

Mettre fin aux discussions et les escalader

// End the current chat session
lifecycleScope.launch {
    try {
        CCAI.chatService?.endChat()
        Log.d("CCAI", "Chat ended successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to end chat: ${e.message}")
    }
}

// Escalate to a human agent
lifecycleScope.launch {
    try {
        CCAI.chatService?.escalateToHumanAgent()
        Log.d("CCAI", "Chat escalated to human agent")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to escalate chat: ${e.message}")
    }
}

// Record the deflection channel the user chose for an existing escalation
// (the escalation must already exist; start one with escalateToHumanAgent())
val escalationOption = ChatEscalationOption(
    escalationId = 123,
    deflectionChannel = DeflectionChannel.Email
)

lifecycleScope.launch {
    try {
        CCAI.chatService?.updateEscalation(option = escalationOption)
        Log.d("CCAI", "Escalation updated successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to update escalation: ${e.message}")
    }
}

// Check the current chat status
lifecycleScope.launch {
    try {
        CCAI.chatService?.checkStatus()
        Log.d("CCAI", "Status check completed successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to check status: ${e.message}")
    }
}

Événements Chat

Envoyez des événements de chat au serveur pour suivre les interactions des utilisateurs. ChatEvent.payload est un Map<String, String> non nullable. Les clés et les valeurs doivent être des chaînes.

val event = ChatEvent(
    name = "form_received",
    payload = mapOf("name" to "contact_form")
)

lifecycleScope.launch {
    try {
        CCAI.chatService?.sendEvent(event)
        Log.d("CCAI", "Event sent successfully")
    } catch (e: Exception) {
        Log.e("CCAI", "Failed to send event: ${e.message}")
    }
}

Les cas d'utilisation courants des événements incluent les interactions avec les formulaires ("form_received", "form_clicked"), les événements d'action intelligente ("smart_action_received", "smart_action_clicked") et les interactions utilisateur personnalisées pour l'analyse.

Remarques sur la compilation spécifiques au module

Tenez compte des points suivants pour une compilation spécifique à un module.

Niveau de SDK minimal

Les modules de couche multimédia CCAIChatRed et CCAICallRed nécessitent min Sdk = 23 (Android 6.0). Si votre application déclare un minSdkVersion inférieur, Gradle ne parviendra pas à fusionner les fichiers manifestes. Augmentez votre min Sdk à au moins 23 dans app/build.gradle.kts :

android {
    defaultConfig {
        minSdk = 23
    }
}