整合工作流必要條件安裝程式庫設定 AWS 憑證開始聊天建立參與者連線使用 WebSocket 連線傳送訊息處理事件結束對話來源碼

將 Amazon Connect 聊天整合到行動應用程式

本節中的主題說明如何在行動應用程式中建立自訂的 Amazon Connect 聊天使用者介面。這需要使用您自己的聊天後端。您還必須使用 Amazon Connect StartChatContactAPI 來啟動聯絡，以及用於管理聊天參與的參與者服務 API。

注意

該 StartChatContact API 需要AWS簽名版本 4 進行簽名。因此，初始請求應通過您的個人聊天後端進行路由。對 Amazon Connect 接參與者服務 (ACP) 的後續 API 呼叫可以直接從行動應用程式處理。

整合工作流

下圖顯示了使用移動應用程序和代理的客戶之間的編程流程。圖表中的編號文字對應於影像下方的編號文字。

在圖中：

當客戶在行動應用程式中開始聊天時，應用程式會使用 StartChatContactAPI 向 Amazon Connect 傳送請求。這需要特定參數 (例如執行個體的 API 端點和 ID 以及聯絡流程)，才能驗證和啟動聊天。
該 StartChatContact API 與您的後端系統進行交互，以獲取參與者令牌和作為聊天會話的唯一標識符的聯繫人 ID。
應用程式的後端會使用參與者權杖和聯絡人 ID 與 Amazon Connect 通訊，並設定客戶的聊天工作階段。
Amazon Connect 參與者 SDK 使用參與者權杖啟動，為聊天做準備應用程式。
參與者 SDK 會使用工作階段詳細資料來建立與 Amazon Connect 的安全通訊線路。
Amazon Connect 通過參與者 SDK 提供 WebSocket URL 進行響應。該應用程序使用此 URL 創建實時消息傳遞的 WebSocket 連接。
Amazon Connect 會根據聯絡流程和路由設定檔為聊天指派支援代理。
來自代理程式的訊息會透過 WebSocket 連線傳送。行動應用程式會接聽， WebSocket 以接收並顯示來自客服的訊息，並將客戶訊息傳回。

必要條件

您必須具備下列先決條件，才能將 Amazon Connect 聊天與行動應用程式整合：

建立一個 Amazon Connect 執行個體。.

—或—

如果您有 Connect 執行個體，請按照下列步驟操作，啟 GitHub 用執行個體的聊天功能。
建立 Amazon Connect 聯絡流程，準備好接收聊天聯絡人。
- 請注意執行個體 ID。
- 尋找 contactFlowId適用的內撥流程範例 (初次聯絡體驗).
部署自訂的 Amazon Connect 聊天後端。請參閱上的 startChatContactAPI 範本 GitHub。
- 部署 L startChatContactambda 函數 CloudFront 範本。
- 將region、API_GATEWAY_IDcontactFlowId、和新增instanceID至範本的 Config 檔案。

安裝程式庫

您可以透過安裝適用於 iOS 和 Android 的程式庫來啟動整合程序。您必須安裝這兩組資源庫。

iOS：轉到aws-sdk-ios存儲庫 GitHub 並安裝以下內容：


pod 'AWSCore'
pod 'AWSConnectParticipant'
pod 'Starscream', '~> 4.0'

Android：轉到aws-sdk-android存儲庫 GitHub 並安裝以下內容：


implementation("com.amazonaws:aws-android-sdk-core:2.73.0")
implementation("com.amazonaws:aws-android-sdk-connectparticipant:2.73.0")

設定 AWS 憑證

安裝兩組程式庫之後，您可以在 Amazon Connect 服務和 Amazon Connect 參與者服務中心註冊。若要這麼做，請在每個作業系統的 Config 檔案中，使用您的AWS認證，accessKey並以空字串 (“”) 取代和secretKey值，如下列範例所示。

重要

您必須指定要測試的區域。

iOS：用AWSStaticCredentialsProvider於 Amazon Connect 服務和參與者服務註冊。


private let config = Config()
 let credentials = AWSStaticCredentialsProvider(accessKey: "", secretKey: "")
 let participantService = AWSServiceConfiguration(region: config.region, credentialsProvider: credentials)!
 AWSConnectParticipant.register(with: participantService, forKey: "")
 connectParticipantClient = AWSConnectParticipant.init(forKey: "")

安卓：初始化AmazonConnectParticipantAsyncClient並設置區域。


private var connectParticipantClient: AmazonConnectParticipantAsyncClient = AmazonConnectParticipantAsyncClient()
private val chatConfiguration = Config
init {
      connectParticipantClient.setRegion(Region.getRegion(chatConfiguration.region))
     }

注意

您可以從中下載 Config 文件 GitHub。您必須編輯這兩個 Config 檔案。

開始聊天

接下來，您必須集成 Amazon Connect 提供的 StartChatContactAPI。該 API 通過註冊客戶的意圖與代理聊天來啟動對話。

注意

若要部署 StartChatContact Lambda 函數，請使用上的CloudFront 範本 GitHub。

對於 iOS 和安卓系統，StartChatContactAPI 調用需要以下幾條信息：

InstanceId：Amazon Connect 執行個體的識別碼。
ContactFlowId：處理聊天的聯繫流程的標識符。
ParticipantDetails：有關參與者的資訊，例如客戶的顯示名稱。
Attributes：有關聯絡人的其他資訊，這些資訊對於在 Amazon Connect 中進行路由傳送或處理聊天可能很有用。

重要

您必須使用AWS簽名版本 4 (SIGv4) 來簽署 API 呼叫。Sigv4 程序會將驗證資訊新增至透過 HTTP 傳送的 AWS API 要求中。對於行動用戶端，我們建議您在伺服器端執行簽署程序。您的行動應用程式會將請求傳送到您的伺服器，然後簽署請求並將其轉寄至 Amazon Connect。這有助於保護您的AWS憑證。

適用於 iOS 系統：


func startChatSession(displayName: String, completion: 
    @escaping (Result<StartChatResponse, Error>) -> Void) {
    // Your back end server will handle SigV4 signing and make the API call to Amazon Connect 
    // Use the completion handler to process the response or error 
}

若為 Android：


// Make a network call to your back end server 
suspend fun startChatSession(displayName: String): StartChatResponse {
    // Your back end server will handle SigV4 signing if needed and make the 
    // API call to Amazon Connect 
    // Handle the response or error accordingly 
}

建立參與者連線

您可以使用從 StartChatContactAPI 呼叫接收到的詳細資料來建立參與者連線。然後您呼叫 AWS Connect 線參與者 SDK，該 SDK 會傳回建立連線所需的 WebSocket URL。

下面的例子演示了如何建立 iOS 的連接：


// Swift code snippet for iOS participant connection setup
/// Creates the participant's connection. https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html
/// - Parameter: participantToken: The ParticipantToken as obtained from StartChatContact API response.
func createParticipantConnection() {
    let createParticipantConnectionRequest = AWSConnectParticipantCreateParticipantConnectionRequest()
    createParticipantConnectionRequest?.participantToken = self.participantToken
    createParticipantConnectionRequest?.types = ["WEBSOCKET", "CONNECTION_CREDENTIALS"]
    connectParticipantClient?
        .createParticipantConnection (createParticipantConnectionRequest!)
        .continueWith(block: {
            (task) -> Any? in
            self.connectionToken = task.result!.connectionCredentials!.connectionToken
            self.websocketUrl = task.result!.websocket!.url
            return nil
        }
        ).waitUntilFinished()
    }

下面的例子演示了如何建立安卓系統的連接：


// Kotlin code snippet for Android participant connection setup
/// Creates the participant's connection. https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html
/// - Parameter: participantToken: The ParticipantToken as obtained from StartChatContact API response.
fun createParticipantConnection(
    _participantToken: String,
      handler: AsyncHandler<CreateParticipantConnectionRequest, CreateParticipantConnectionResult>
    ) {
          val createParticipantConnectionRequest = CreateParticipantConnectionRequest().apply {
              setType(listOf("WEBSOCKET", "CONNECTION_CREDENTIALS"))
              participantToken = _participantToken
       }
          connectParticipantClient.createParticipantConnectionAsync(
              createParticipantConnectionRequest,
              handler
        )
    }

使用 WebSocket 連線

使用參與者 SDK 取得聊天連線的 WebSocket URL。

要實施 WebSocket 管理，使用現有的解決方案或實施自己的解決方案
要處理 Websocket 的消息和事件，實現您自己的解決方案，或使用我們的解決方案適用於 iOS 和 Android 的解決方案。
請確定您涵蓋所有訊息和事件類型：
- 案例 typing = "application/vnd.amazonaws.connect.event.typing"
- 案例 messageDelivered = "application/vnd.amazonaws.connect.event.message.delivered"
- 案例 messageRead = "application/vnd.amazonaws.connect.event.message.read"
- 案例 metaData = "application/vnd.amazonaws.connect.event.message.metadata"
- 案例 joined = "application/vnd.amazonaws.connect.event.participant.joined"
- 案例 left = "application/vnd.amazonaws.connect.event.participant.left"
- 案例 ended = "application/vnd.amazonaws.connect.event.chat.ended"
- 案例 plainText = "text/plain"
- 案例 richText = "text/markdown"
- 案例 interactiveText = "application/vnd.amazonaws.connect.message.interactive"

下圖顯示了 Connect 聊天的默認實例。圖像中的數字對應於下面的編號文本。

在圖像中，從頂部附近開始：

輸入指示器會顯示輸入訊息的人員。
此範例使用純文字訊息。如果需要，您可以啟用降價的使用。
互動式清單控制項為使用者提供選項清單，例如客戶服務或帳單。
互動式快速回覆可針對常見問題或片語提供預先編程的回應。

傳送訊息

您可以使用該SendMessage功能發送聊天消息。


/// To send a message using the Participant SDK.
/// - Parameters:
///   - messageContent: The content of the message.
///   - connectionToken: The authentication token associated with the connection - Received from Participant Connection
///   - contentType: text/plain, text/markdown, application/json, and application/vnd.amazonaws.connect.message.interactive.response
func sendChatMessage(messageContent: String) {
    let sendMessageRequest = AWSConnectParticipantSendMessageRequest()
    sendMessageRequest?.connectionToken = self.connectionToken
    sendMessageRequest?.content = messageContent
    sendMessageRequest?.contentType = "text/plain"
    connectParticipantClient?
        .sendMessage(sendMessageRequest!)
        .continueWith(block: { (task) -> Any? in
            return nil
        })
}

處理事件

使用參與者 SDK 中的SendEvent函數來處理輸入和讀取回條等事件。


/// Sends an event such as typing, joined, left etc.
/// - Parameters:
///   - contentType: The content type of the request
///   - content: The content of the event to be sent (for example, message text). For content related to message receipts, this is supported in the form of a JSON string.
func sendEvent(contentType: ContentType, content: String = "") {
    let sendEventRequest = AWSConnectParticipantSendEventRequest()
    sendEventRequest?.connectionToken = self.connectionToken
    sendEventRequest?.contentType = contentType.rawValue
    sendEventRequest?.content = content // Set the content here
    connectParticipantClient?
        .sendEvent(sendEventRequest!)
        .continueWith(block: { (task) -> Any? in
            return nil
        })
}

結束對話

若要結束聊天，請使用參與者 SDK 中的disconnectParticipant功能。


/// Disconnects a participant.
/// - Parameter: connectionToken: The authentication token associated with the connection - Received from Participant Connection
func endChat() {
    let disconnectParticipantRequest = AWSConnectParticipantDisconnectParticipantRequest()
    disconnectParticipantRequest?.connectionToken = self.connectionToken
    connectParticipantClient?.disconnectParticipant(disconnectParticipantRequest!)
        .continueWith(block: { (task) -> Any? in
            return nil
        }).waitUntilFinished()
    self.websocketUrl = nil
}

來源碼

下面的示例項目顯 GitHub 示了如何實現 Connect 聊天。

iOS：iOS 的原生聊天演示。
安卓：安卓本機聊天演示。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

針對您的通訊小工具的問題進行故障診斷

建立快速回應