Android용 헤드리스 모바일 SDK: 대기열, 채널, 채팅

이 문서에서는 앱에서 지원 진입점(대기열 및 채널)을 제공하는 방법과 전체 채팅 수명 주기(시작, 재개, 메시지 및 첨부파일 전송, 입력 표시, 민감한 정보 수정, 상담사에게 에스컬레이션, 세션 종료)를 관리하는 방법을 설명합니다.

시작하기 전에

SDK를 설정합니다. 자세한 내용은 Android용 헤드리스 모바일 SDK: 시작하기를 참고하세요.

대기열 및 채널 선택

  • 대기열은 일반적으로 '결제', '기술 지원' 또는 'VIP 지원'과 같은 지원 진입점을 나타냅니다.

  • 각 대기열은 다음 채널 중 하나 이상을 제공할 수 있습니다.

    • 채팅

    • 즉석 통화(음성)

    • 예약된 통화

    • 이메일

    • 외부 디플렉션 링크(셀프 서비스 페이지 또는 기타 채널 링크)

큐 및 채널 가용성은 관리자가 Contact Center AI Platform 관리 포털에서 구성합니다.

앱에 표시되는 방식

앱의 일반적인 흐름은 다음과 같습니다.

  1. 앱에 지원 진입점(예: 도움말 탭 또는 문의하기 버튼)을 추가합니다.

  2. 사용자가 탭하면 SDK를 사용하여 대기열 메뉴를 가져오고 자체 메뉴 UI를 렌더링합니다.

  3. 사용자가 대기열을 선택하면 사용 가능한 채널을 검사합니다.

  4. 앱은 사용자에게 이러한 채널을 표시합니다(예: 지금 채팅, 지금 전화, 통화 예약, 이메일 보내기, 고객센터 방문).

  5. 사용자가 채널을 선택하면 해당 SDK API를 호출합니다.

SDK에서 대기열 메뉴 가져오기

SDK는 대기열 메뉴를 가져오는 queueMenuService를 제공합니다. get 메서드는 큐 목록(List<QueueMenu>)과 isDirectAccess 플래그가 포함된 QueueMenuResult를 반환합니다. 전체 메뉴 트리를 가져오거나 직접 액세스 키를 사용하여 특정 대기열로 바로 이동할 수 있습니다.

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

선택적 key 매개변수를 사용하면 전체 대기열 메뉴를 우회하고 사용자를 특정 대기열로 바로 이동할 수 있습니다. CCAI Platform 플랫폼에서는 직접 액세스 포인트(DAP)를 통해 이를 수행합니다.

DAP는 CCAI Platform 포털에서 관리자가 다음과 같은 방법으로 구성할 수 있습니다.

  1. 설정 > 대기열로 이동하여 메뉴 구조에서 대기열을 선택합니다.

  2. 액세스 포인트 섹션에서 + 직접 액세스 포인트 만들기를 클릭합니다.

  3. 텍스트 양식에 키를 입력합니다.

  4. 저장을 클릭합니다.

QueueMenu 데이터 구조

각 QueueMenu에는 다음이 포함됩니다.

속성 유형 설명
id 정수 이 큐의 고유 식별자입니다.
name 문자열? 표시 이름입니다(예: '결제 지원').
children List<QueueMenu> 하위 메뉴(리프 노드인 경우 빈 목록)입니다.
channels 채널 이 큐에 사용할 수 있는 채널입니다.
hidden 불리언 이 대기열을 소비자에게 숨겨야 하는지 여부입니다(관리자가 구성함).
position Int? 서버 정의 표시 위치 - 관리자 포털 순서를 유지합니다.
settings List<QueueMenuSetting>? 관리자 포털에서 구성된 대기열 수준 설정입니다.
redirectionExtra QueueMenuRedirection? 구성된 경우 자동 리디렉션 메타데이터(리디렉션 및 편향 참조)
deflectionFrom List<QueueMenuDeflection>? 이 대기열로 전환된 대기열입니다. 플랫폼은 이 대기열을 대신 반환하므로 비어 있지 않은 목록은 이미 발생한 리디렉션을 설명합니다(Deflection 참고).

Channels 데이터 클래스에는 다음과 같은 속성이 있습니다.

속성 유형 설명
chat ChatChannel? 채팅 채널 구성(이 대기열에서 채팅을 사용할 수 없는 경우 null)
voiceCall VoiceCallChannel? 음성 통화 채널 구성(음성을 사용할 수 없는 경우 null) scheduleEnabled와 같은 플래그와 녹음 환경설정이 포함됩니다.
email EmailChannel? 이메일 채널 구성(이메일을 사용할 수 없는 경우 null) channels.email?.email을 사용하여 주소에 액세스합니다.
externalDeflectionLink ExternalDeflectionLink? 외부 디플렉션 링크 구성(사용할 수 없는 경우 null) 구조화된 유형의 속성을 사용하여 URL에 액세스합니다.

VoiceCallChannel 필드(기능 및 디플렉션 메타데이터)

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

구현 예시

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

대기 시간 가져오는 중

특정 대기열의 예상 대기 시간을 가져올 수도 있습니다.

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

단일 채널 대기열

대기열에서 하나의 채널(예: 이메일만)만 제공하는 경우 다음을 수행할 수 있습니다.

  • 채널 선택 단계를 건너뛰고 적절한 UI로 바로 이동합니다.

  • 또는 UX에서 더 적합한 경우 사용 가능한 채널을 명시적으로 표시할 수도 있습니다.

SDK의 구성 및 메타데이터는 허용되는 채널을 알려주고 앱은 이를 표시하는 방법을 결정합니다.

리디렉션 및 디플렉션

관리자는 채널을 제공하는 대신 사용자를 리디렉션하도록 대기열을 구성할 수 있습니다. QueueMenu.redirectionExtra가 설정되면 사용자가 대기열을 선택하는 즉시 조치를 취합니다.

  • option는 수행할 작업을 나타냅니다(PHONE, MESSAGE, URL, VOICEMAIL, QUEUE, SIP 또는 CONTACT).
  • data는 전화 걸 번호, 표시할 메시지, 열 URL과 같은 값을 전달합니다.

QueueMenu.deflectionFrom은 다릅니다. 큐가 다른 큐로 편향되면 플랫폼은 사용자가 선택한 큐 대신 대상 큐를 반환하고 deflectionFrom에 소스 큐를 나열합니다. 이미 발생한 리디렉션을 설명하는 것이며 제공할 옵션 집합이 아닙니다.

영업시간 외 및 수용 인원 초과로 인한 전환은 채널별로 보고됩니다. 처리 방법은 Android용 헤드리스 모바일 SDK: 스마트 작업, 첨부파일, 이탈을 참고하세요.

채널

헤드리스 모바일 SDK에서 CCAI Platform 관리자 포털은 지원 작업의 정보 소스 역할을 합니다. 관리자는 다양한 지원 대기열(예: '결제' 또는 '기술 지원')에 사용할 수 있는 지원 채널(예: 채팅, 음성, 이메일 또는 유용한 링크)을 구성합니다.

SDK는 이 구성을 안전하게 가져와 앱에 전달하는 역할을 합니다. 앱은 이 구성을 읽고 적절한 사용자 인터페이스를 그리는 역할을 합니다.

사용 가능한 채널 검사

SDK에서 제공하는 기능: 사용자가 선택한 특정 대기열에 대해 활성 상태이고 사용 가능한 지원 채널의 실시간 스냅샷을 제공하며, 포털의 영업시간 및 용량 제한을 준수합니다.

빌드하는 항목: 사용자에게 사용 가능한 옵션을 표시하는 UI 메뉴(버튼, 목록 또는 카드)입니다.

구현 예: 다음 Kotlin 코드는 사용자가 방금 탭한 대기열을 가져와 Channels 데이터 클래스를 검사하여 사용 설정된 채널을 확인합니다. 그런 다음 화면에 표시할 버튼을 결정합니다.

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

다음 섹션에서는 채팅에 대해 자세히 설명합니다. 음성, 화면 공유, 예약된 통화, 이메일, 외부 편향 링크는 Android용 헤드리스 모바일 SDK: 음성, 화면 공유, 예약된 통화, 이메일을 참고하세요.

Chat 서비스 API

chatService는 전체 채팅 수명 주기를 관리합니다. 가장 자주 사용하는 핵심 메서드는 다음과 같습니다.

메서드 설명
start ChatRequest와 새 채팅 세션을 시작합니다.
sendMessage 메시지(텍스트, 이미지, 동영상 또는 양식 이벤트)를 전송합니다.
typing 입력 표시기를 업데이트합니다.
endChat 현재 채팅 세션을 종료합니다.
resumeChat 이전에 설정된 채팅 세션을 재개합니다.
escalateToHumanAgent 가상 에이전트에서 상담사로의 트랜스퍼
checkStatus 서버에서 현재 채팅 상태를 새로고침합니다.

ChatRequest 및 ChatResponse 데이터 구조

ChatRequest 데이터 클래스에는 새 채팅을 시작하기 위한 구성이 포함되어 있습니다.

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

채팅을 시작하거나 재개하면 SDK는 chatReceived 흐름에서 ChatResponse를 전달합니다(start() 및 resumeChat()는 아무것도 반환하지 않음). 이 가이드에서 가장 많이 참조하는 속성은 다음과 같습니다.

  • id - 고유한 채팅 세션 식별자입니다.

  • status - 현재 채팅 상태(대기 중, 활성, 종료 등)

  • agent / virtualAgent - 할당된 상담사 또는 가상 에이전트입니다.

  • postSessionRequired - 세션에 세션 후 가상 에이전트가 구성되었는지 여부 설문조사 및 CSAT는 surveyEnabled 및 csatSetting로 표시됩니다.

  • redactionEnabled - 이 세션에 자동 개인 식별 정보(PII) 수정이 활성화되어 있는지 여부입니다.

채팅 세션 시작하기

채팅 세션을 시작하려면 chatService를 사용하고 ChatRequest로 대기열 메뉴 ID를 지정합니다.

간단한 예시

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

앱에 CCAIScreenShare 모듈이 포함되어 있지 않으면 screenShareService 가져오기와 isScreenShareable 인수를 삭제합니다.

저속한 언어 사용

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

채팅 세션 재개하기

ChatResponse 객체를 사용하여 이전에 설정된 채팅 세션을 재개합니다.

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

채팅 대기열 관리

현재 채팅을 다시 대기열에 넣거나(상태가 대기 중으로 변경됨) 기존의 진행 중인 채팅을 확인할 수 있습니다.

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

메시지 보내기

sendMessage 메서드는 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()
}

UploadableImage 및 UploadableVideo 유형(com.ccaiplatform.ccaikit.models.smartaction)은 업로드할 미디어를 래핑합니다.

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는 이미지 목록을, Videos는 단일 동영상을 사용합니다. 사용자가 대기열에서 대기 중이거나 업로드가 대기 중인 동안에는 대용량 미디어 애셋을 메모리에 보관하지 마세요.

사용 예시

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

ScreenShare 메시지 유형은 화면 공유 이벤트 및 응답을 서버에 전송하는 데 사용됩니다. 사용 가능한 화면 공유 이벤트는 다음과 같습니다.

  • screenShareRequestedFromAgent - 상담사가 화면 공유를 요청함

  • screenShareRequestedFromEndUser - 최종 사용자가 화면 공유를 요청함

  • screenShareCodeGenerated - 화면 공유 코드가 생성됨

  • screenShareFailed - 화면 공유 실패

  • screenShareStarted - 화면 공유 세션 시작됨

  • screenShareEnded - 화면 공유 세션 종료됨

입력 표시기 및 메시지 미리보기

사용자가 입력하는 동안 입력 상태를 업데이트하고 메시지 미리보기를 전송합니다.

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

메시지 수정

일반 텍스트 채팅 메시지 및 메시지 프리뷰에 민감한 정보(PII, 신용카드 번호 등)의 자동 수정이 지원됩니다.

수정 구성:

  • ChatResponse의 redactionEnabled 속성에 의해 제어됩니다.

  • 포털의 설정 > 채팅 설정 > 자동 수정에서 구성됩니다.

  • 사용 설정하면 민감한 정보가 상담사에게 전송되기 전에 자리표시자로 자동으로 대체됩니다.

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

채팅 종료 및 에스컬레이션

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

채팅 이벤트

사용자 상호작용을 추적하기 위해 채팅 이벤트를 서버로 전송합니다. ChatEvent.payload는 null을 허용하지 않는 Map<String, 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}")
    }
}

일반적인 이벤트 사용 사례에는 양식 상호작용('form_received', 'form_clicked'), 스마트 액션 이벤트('smart_action_received', 'smart_action_clicked'), 분석을 위한 맞춤 사용자 상호작용이 포함됩니다.

모듈별 빌드 고려사항

모듈별 빌드의 경우 다음을 고려하세요.

최소 SDK 수준

CCAIChatRed 및 CCAICallRed 미디어 레이어 모듈에는 min Sdk = 23(Android 6.0)이 필요합니다. 앱에서 더 낮은 minSdkVersion를 선언하면 Gradle은 매니페스트를 병합하지 못합니다. app/build.gradle.kts에서 min Sdk를 23 이상으로 높이세요.

android {
    defaultConfig {
        minSdk = 23
    }
}