Android 向けヘッドレス モバイル SDK: キュー、チャネル、チャット

このドキュメントでは、アプリでサポート エントリ ポイント(キューとチャネル)を利用できるようにする方法と、チャットのライフサイクル全体(開始、再開、メッセージと添付ファイルの送信、入力の表示、機密データの削除、人間のエージェントへのエスカレーション、セッションの終了)を管理する方法について説明します。

始める前に

SDK を設定します。詳細については、Android 向けヘッドレス モバイル SDK: スタートガイドをご覧ください。

キューとチャネルを選択する

  • キューは通常、「請求」、「テクニカル サポート」、「VIP サポート」などのサポート エントリ ポイントを表します。

  • 各キューでは、次のチャネルを 1 つ以上提供できます。

    • チャット

    • インスタント通話(音声)

    • スケジュールされた通話

    • メール

    • 外部デフレクション リンク(セルフサービス ページや他のチャネルへのリンク)

キューとチャネルの可用性は、コンタクト センター AI プラットフォーム管理ポータルで管理者が構成します。

アプリでの表示

アプリでの一般的なフローは次のとおりです。

  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)を使用して実現されます。

管理者は、CCAI Platform ポータルで DAP を次のように構成できます。

  1. [設定] > [キュー] に移動し、メニュー構造からキューを選択します。

  2. [アクセス ポイント] セクションで、[+ ダイレクト アクセス ポイントを作成] をクリックします。

  3. テキスト フォームにキーを入力します。

  4. [保存] をクリックします。

QueueMenu のデータ構造

各 QueueMenu には次のものが含まれます。

プロパティ 型 説明
id Int このキューの固有識別子。
name String? 表示名(例: 「Billing Support」)。
children List<QueueMenu> サブメニュー(リーフノードの場合は空のリスト)。
channels チャネルですか? このキューで使用可能なチャネル。
hidden ブール値 このキューをコンシューマーに表示しないかどうか(管理者が構成)。
position Int? サーバー定義の表示位置 - 管理者ポータルの順序を保持します。
settings List<QueueMenuSetting>? 管理者ポータルで構成されたキューレベルの設定。
redirectionExtra QueueMenuRedirection? 構成されている場合は、自動リダイレクト メタデータ(リダイレクトとデフレクションを参照)。
deflectionFrom List<QueueMenuDeflection>? このキューに転送されたキュー。プラットフォームは、このキューを代わりに返します。そのため、空でないリストは、すでに発生したリダイレクトを示します(デフレクションを参照)。

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)

単一チャネルのキュー

キューで 1 つのチャネル(メールのみなど)しか提供されていない場合は、次の操作を行えます。

  • チャンネル選択ステップをスキップして、適切な UI に直接移動します。

  • また、UX でより意味がある場合は、利用可能なチャンネルを明示的に表示することもできます。

SDK の構成とメタデータによって、許可されるチャネルがわかります。アプリは、それらを表示する方法を決定します。

リダイレクトとデフレクション

管理者は、オファー配信チャネルを提供する代わりに、ユーザーをリダイレクトするようにキューを構成できます。QueueMenu.redirectionExtra が設定されている場合は、ユーザーがキューを選択するとすぐに処理します。

  • option は、実行する操作(PHONE、MESSAGE、URL、VOICEMAIL、QUEUE、SIP、CONTACT)を示します。
  • data は、ダイヤルする番号、表示するメッセージ、開く URL などの値を保持します。

QueueMenu.deflectionFrom は違います。キューが別のキューにデフレクトされると、プラットフォームはユーザーが選択したキューの代わりにデフレクト先のキューを返し、deflectionFrom にデフレクト元のキューをリストします。これは、すでに発生したリダイレクトについて説明するものであり、提供するオプションのセットではありません。

営業時間外および対応可能件数超過時の転送は、チャネルごとに報告されます。処理方法については、Android 向けヘッドレス モバイル SDK: スマート アクション、添付ファイル、リダイレクトをご覧ください。

チャンネル

Headless Mobile 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 向け Headless Mobile 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 Flow で ChatResponse を配信します(start() と resumeChat() は何も返しません)。このガイドで主に使用するプロパティは次のとおりです。

  • id - チャット セッションの固有識別子。

  • status - 現在のチャット ステータス(キューに登録済み、アクティブ、終了など)。

  • agent / virtualAgent - 割り当てられた人間のエージェントまたは仮想エージェント。

  • postSessionRequired - セッションにセッション後の仮想エージェントが構成されているかどうか。アンケートと CSAT は surveyEnabled と csatSetting で示されます。

  • redactionEnabled - このセッションで個人情報の自動削除が有効になっているかどうか。

チャット セッションを開始する

チャット セッションを開始するには、キューメニュー ID を指定する ChatRequest を指定して chatService を使用します。

最も簡単な例

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 は 1 つの動画を受け取ります。ユーザーがキューで待機している間や、アップロードが保留されている間は、サイズの大きなメディア アセットをメモリに保持しないようにします。

使用例

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

Chat イベント

ユーザー インタラクションをトラッキングするために、チャット イベントをサーバーに送信します。 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
    }
}