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:
Anda menambahkan titik entri dukungan di aplikasi (misalnya, tab Bantuan atau tombol Hubungi Kami).
Saat pengguna mengetuknya, Anda akan mengambil menu antrean menggunakan SDK dan merender UI menu Anda sendiri.
Saat pengguna memilih antrean, Anda memeriksa saluran yang tersedia.
Aplikasi Anda menampilkan saluran tersebut kepada pengguna (misalnya, Chat sekarang, Telepon sekarang, Jadwalkan panggilan, Kirim email kepada kami, Buka Pusat Bantuan).
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:
Buka Setelan > Antrean > Pilih antrean dari struktur menu.
Dari bagian Access Point, klik + Create direct access point.
Masukkan kunci di formulir teks.
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:
optionmemberi tahu tindakan yang harus dilakukan: PHONE, MESSAGE, URL, VOICEMAIL, QUEUE, SIP, atau CONTACT.datamembawa 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 dengansurveyEnableddancsatSetting.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 layarscreenShareRequestedFromEndUser- pengguna akhir meminta berbagi layarscreenShareCodeGenerated- kode berbagi layar telah dibuatscreenShareFailed- berbagi layar gagalscreenShareStarted- sesi berbagi layar dimulaiscreenShareEnded- 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
redactionEnableddiChatResponse.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
}
}