SDK seluler tanpa UI untuk Android: Antrean, saluran, dan chat

Dokumen ini menjelaskan cara menyediakan titik entri dukungan (antrean dan saluran) di aplikasi Anda, dan cara mendorong siklus proses chat lengkap: memulai, melanjutkan, mengirim pesan dan lampiran, menunjukkan pengetikan, menyamarkan data sensitif, mengeskalasi ke agen manusia, dan mengakhiri sesi.

Sebelum memulai

Siapkan SDK. Untuk mengetahui informasi selengkapnya, lihat SDK seluler headless untuk Android: Memulai.

Memilih antrean dan saluran

  • Antrean biasanya mewakili titik entri dukungan, seperti "Penagihan", "Dukungan Teknis", atau "Dukungan VIP".

  • Setiap antrean dapat menawarkan satu atau beberapa saluran berikut:

    • Chat

    • Panggilan instan (suara)

    • Panggilan terjadwal

    • Email

    • Link pengalihan eksternal (link ke halaman layanan mandiri atau saluran lainnya)

Antrean dan ketersediaan saluran dikonfigurasi oleh administrator di Portal Admin Contact Center AI Platform.

Tampilan di aplikasi Anda

Di aplikasi Anda, alur umumnya adalah:

  1. Anda menambahkan titik entri dukungan di aplikasi (misalnya, tab Bantuan atau tombol Hubungi Kami).

  2. Saat pengguna mengetuknya, Anda akan mengambil menu antrean menggunakan SDK dan merender UI menu Anda sendiri.

  3. Saat pengguna memilih antrean, Anda memeriksa saluran yang tersedia.

  4. Aplikasi Anda menampilkan saluran tersebut kepada pengguna (misalnya, Chat sekarang, Telepon sekarang, Jadwalkan panggilan, Kirim email kepada kami, Buka Pusat Bantuan).

  5. Saat pengguna memilih saluran, Anda memanggil API SDK yang sesuai.

Mengambil menu antrean dari SDK

SDK menyediakan queueMenuService untuk mengambil menu antrean. Metode get menampilkan QueueMenuResult yang berisi daftar antrean (List<QueueMenu>) dan flag isDirectAccess. Anda dapat mengambil hierarki menu lengkap atau menggunakan Kunci Akses Langsung untuk langsung beralih ke antrean tertentu:

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")

Parameter key opsional memungkinkan Anda mengabaikan menu antrean lengkap dan langsung mengarahkan pengguna ke antrean tertentu. Di platform CCAI Platform, hal ini dicapai dengan titik akses langsung (DAP).

DAP dapat dikonfigurasi oleh administrator di portal CCAI Platform dengan cara berikut:

  1. Buka Setelan > Antrean > Pilih antrean dari struktur menu.

  2. Dari bagian Access Point, klik + Create direct access point.

  3. Masukkan kunci di formulir teks.

  4. Klik Simpan.

Struktur data QueueMenu

Setiap QueueMenu berisi:

Properti Jenis Deskripsi
id Int ID unik untuk antrean ini.
name String? Nama tampilan (misalnya, "Dukungan Penagihan").
children List<QueueMenu> Sub-menu (daftar kosong jika ini adalah node daun).
channels Channel? Saluran yang tersedia untuk antrean ini.
hidden Boolean Apakah antrean ini harus disembunyikan dari konsumen (dikonfigurasi oleh administrator).
position Int? Posisi tampilan yang ditentukan server - mempertahankan pengurutan portal administrator.
settings List<QueueMenuSetting>? Setelan tingkat antrean yang dikonfigurasi di portal administrator.
redirectionExtra QueueMenuRedirection? Metadata pengalihan otomatis saat dikonfigurasi (lihat Pengalihan dan defleksi).
deflectionFrom List<QueueMenuDeflection>? Antrean yang dialihkan ke antrean ini. Platform menampilkan antrean ini sebagai gantinya, sehingga daftar yang tidak kosong menjelaskan pengalihan yang telah terjadi (lihat Defleksi)

Class data Channels memiliki properti berikut:

Properti Jenis Deskripsi
chat ChatChannel? Konfigurasi saluran chat (null jika chat tidak tersedia untuk antrean ini).
voiceCall VoiceCallChannel? Konfigurasi saluran panggilan suara (null jika suara tidak tersedia). Berisi flag seperti scheduleEnabled dan preferensi perekaman.
email EmailChannel? Konfigurasi saluran email (null jika email tidak tersedia). Akses alamat menggunakan channels.email?.email.
externalDeflectionLink ExternalDeflectionLink? Konfigurasi link pengalihan eksternal (null jika tidak tersedia). Akses URL menggunakan properti jenis terstruktur.

Kolom VoiceCallChannel (metadata kemampuan dan defleksi)

// 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?
)

Contoh penerapan

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()
}

Mengambil waktu tunggu

Anda juga dapat mengambil perkiraan waktu tunggu untuk antrean tertentu:

// 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)

Antrean saluran tunggal

Jika antrean hanya menawarkan satu saluran (misalnya, hanya email), Anda dapat:

  • Lewati langkah pemilihan saluran dan langsung buka UI yang sesuai.

  • Atau, Anda masih dapat menampilkan saluran yang tersedia secara eksplisit jika hal itu lebih masuk akal dalam UX Anda.

Konfigurasi dan metadata SDK memberi tahu Anda saluran mana yang diizinkan; aplikasi Anda memutuskan cara menampilkannya.

Pengalihan dan defleksi

Admin dapat mengonfigurasi antrean untuk mengalihkan pengguna, bukan menawarkan saluran. Saat QueueMenu.redirectionExtra ditetapkan, lakukan tindakan segera setelah pengguna memilih antrean:

  • option memberi tahu tindakan yang harus dilakukan: PHONE, MESSAGE, URL, VOICEMAIL, QUEUE, SIP, atau CONTACT.
  • data membawa nilai, seperti nomor yang akan dihubungi, pesan yang akan ditampilkan, atau URL yang akan dibuka.

QueueMenu.deflectionFrom berbeda. Saat antrean dialihkan ke antrean lain, platform akan menampilkan antrean tujuan, bukan antrean yang dipilih pengguna, dan mencantumkan antrean sumber di deflectionFrom. Pesan ini menjelaskan pengalihan yang telah terjadi; bukan serangkaian opsi yang ditawarkan.

Pengalihan di luar jam kerja dan kelebihan kapasitas dilaporkan per saluran. Untuk mengetahui cara menanganinya, lihat Mobile SDK Headless untuk Android: Smart Action, Lampiran, dan Pengalihan.

Saluran

Di Headless Mobile SDK, portal administrator CCAI Platform bertindak sebagai sumber kebenaran untuk operasi dukungan Anda. Administrator mengonfigurasi saluran dukungan (seperti chat, suara, email, atau link bermanfaat) yang tersedia untuk antrean dukungan yang berbeda (seperti "Penagihan" atau "Dukungan Teknis").

Tugas SDK adalah mengambil konfigurasi ini dengan aman dan menyerahkannya ke aplikasi Anda. Tugas aplikasi Anda adalah membaca konfigurasi tersebut dan menggambar antarmuka pengguna yang sesuai.

Memeriksa saluran yang tersedia

Yang disediakan SDK: Ringkasan real-time tentang saluran dukungan yang aktif dan tersedia untuk antrean tertentu yang dipilih pengguna, dengan mempertimbangkan jam kerja dan batas kapasitas portal Anda.

Yang Anda buat: Menu UI (tombol, daftar, atau kartu) yang menampilkan opsi yang tersedia ini kepada pengguna.

Contoh implementasi: Kode Kotlin berikut mengambil antrean yang baru saja diketuk pengguna dan memeriksa class data Channels untuk melihat saluran mana yang diaktifkan. Kemudian, sistem akan memutuskan tombol mana yang akan ditampilkan di layar.

// 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()
    }
}

Bagian berikut membahas chat secara mendetail. Untuk link suara, berbagi layar, panggilan terjadwal, email, dan pengalihan eksternal, lihat Headless Mobile SDK untuk Android: Suara, Berbagi Layar, Panggilan Terjadwal, dan Email

Chat service API

chatService mengelola siklus proses chat lengkap. Metode inti yang paling sering Anda gunakan adalah:

Metode Deskripsi
start Memulai sesi chat baru dengan ChatRequest.
sendMessage Mengirim pesan (teks, gambar, video, atau peristiwa formulir).
typing Memperbarui indikator mengetik.
endChat Mengakhiri sesi chat saat ini.
resumeChat Melanjutkan sesi chat yang telah dibuat sebelumnya.
escalateToHumanAgent Transfer dari agen virtual ke agen manusia.
checkStatus Memperbarui status chat saat ini dari server.

Struktur data ChatRequest dan ChatResponse

Class data ChatRequest berisi konfigurasi untuk memulai chat baru:

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)
)

Setelah Anda memulai atau melanjutkan chat, SDK akan mengirimkan ChatResponse-nya di Flow chatReceived (start() dan resumeChat() tidak menampilkan apa pun). Properti yang paling sering Anda referensikan dalam panduan ini meliputi:

  • id - ID sesi chat unik.

  • status - status chat saat ini (dalam antrean, aktif, berakhir, dll.).

  • agent / virtualAgent - agen manusia atau virtual yang ditugaskan.

  • postSessionRequired - apakah agen virtual pasca-sesi dikonfigurasi untuk sesi tersebut. Survei dan CSAT ditandai dengan surveyEnabled dan csatSetting.

  • redactionEnabled - apakah penyajian ulang PII otomatis aktif untuk sesi ini.

Memulai sesi chat

Untuk memulai sesi chat, gunakan chatService dengan ChatRequest yang menentukan ID menu antrean.

Contoh 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}")
        }
    }
}

Jika aplikasi Anda tidak menyertakan modul CCAIScreenShare, hapus impor screenShareService dan argumen isScreenShareable.

Dengan kata-kata vulgar

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

Melanjutkan sesi chat

Lanjutkan sesi chat yang telah dibuat sebelumnya menggunakan objek ChatResponse:

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

Pengelolaan antrean chat

Anda dapat mengembalikan chat saat ini ke antrean (statusnya menjadi dalam antrean) atau memeriksa chat yang sedang berlangsung:

// 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}")
    }
}

Mengirim pesan

Metode sendMessage mendukung beberapa jenis pesan melalui class tertutup 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()
}

Jenis UploadableImage dan UploadableVideo (di com.ccaiplatform.ccaikit.models.smartaction) menggabungkan media untuk diupload:

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 mengambil daftar gambar; Videos mengambil satu video. Hindari menyimpan aset media berukuran besar dalam memori saat pengguna sedang menunggu dalam antrean atau saat upload tertunda.

Contoh penggunaan

// 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}")
    }
}

Jenis pesan ScreenShare digunakan untuk mengirim peristiwa dan respons berbagi layar ke server. Peristiwa berbagi layar yang tersedia meliputi:

  • screenShareRequestedFromAgent - agen meminta berbagi layar

  • screenShareRequestedFromEndUser - pengguna akhir meminta berbagi layar

  • screenShareCodeGenerated - kode berbagi layar telah dibuat

  • screenShareFailed - berbagi layar gagal

  • screenShareStarted - sesi berbagi layar dimulai

  • screenShareEnded - sesi berbagi layar berakhir

Indikator mengetik dan pratinjau pesan

Perbarui status pengetikan dan kirim pratinjau pesan saat pengguna mengetik:

// 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}")
        }
    }
}

Penyamaran pesan

Penyuntingan otomatis informasi sensitif (PII, nomor kartu kredit, dll.) didukung untuk pesan chat teks biasa dan pratinjau pesan.

Konfigurasi penyamaran:

  • Dikontrol oleh properti redactionEnabled di ChatResponse.

  • Dikonfigurasi di portal di bagian Settings > Chat Settings > Automatic Redaction.

  • Jika diaktifkan, data sensitif akan otomatis diganti dengan placeholder sebelum dikirim ke agen.

// 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}")
    }
}

Mengakhiri dan mengeskalasi chat

// 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}")
    }
}

Peristiwa chat

Mengirim peristiwa chat ke server untuk melacak interaksi pengguna. ChatEvent.payload adalah Map<String, String> non-nullable — kunci dan nilai harus berupa string.

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}")
    }
}

Kasus penggunaan peristiwa umum mencakup interaksi formulir ("form_received", "form_clicked"), peristiwa tindakan cerdas ("smart_action_received", "smart_action_clicked"), dan interaksi pengguna kustom untuk analisis.

Pertimbangan build khusus modul

Pertimbangkan hal berikut untuk build khusus modul.

Level SDK minimum

Modul lapisan media CCAIChatRed dan CCAICallRed memerlukan min Sdk = 23 (Android 6.0). Jika aplikasi Anda mendeklarasikan minSdkVersion yang lebih rendah, Gradle akan gagal menggabungkan manifes. Naikkan min Sdk Anda ke setidaknya 23 di app/build.gradle.kts:

android {
    defaultConfig {
        minSdk = 23
    }
}