集成工作流先决条件安装库配置 AWS 凭证开始聊天创建参与者连接使用 WebSocket 连接发送消息处理事件结束聊天源代码

将 Amazon Connect 聊天集成到移动应用程序中

本节中的主题说明了如何在您的移动应用程序中构建自定义 Amazon Connect 聊天用户界面。这需要使用您自己的聊天后端。您还必须使用 Amazon Connect StartChatContactAPI 发起联系，并使用参与者服务 API 来管理聊天参与情况。

注意

StartChatContactAPI 需要AWS签名版本 4 签名。因此，初始请求应通过您的个人聊天后端发送。后续对 Amazon Connect 参与者服务 (ACPS) 的 API 调用可以直接从移动应用程序中处理。

集成工作流

下图显示了使用移动应用程序的客户和代理之间的编程流程。图表中的编号文本对应于图像下方的带编号的文本。

在图中：

当客户在移动应用程序中开始聊天时，该应用程序会使用 StartChatContactAPI 向 Amazon Connect 发送请求。这需要特定的参数，例如实例的 API 端点和 ID 以及联系流，才能进行身份验证和启动聊天。
StartChatContactAPI 与您的后端系统交互以获取作为聊天会话唯一标识符的参与者令牌和联系人 ID。
该应用程序的后端使用参与者令牌和联系人 ID 与 Amazon Connect 通信，从而设置客户的聊天会话。
使用参与者令牌激活 Amazon Connect 参与者软件开发工具包，为聊天做好准备。
参与者软件开发工具包使用会话详细信息与 Amazon Connect 建立安全的通信线路。
Amazon Connect 的回应是通过参与者软件开发工具包提供 WebSocket 网址。该应用程序使用此 URL 来创建用于实时消息的 WebSocket 连接。
Amazon Connect 根据联系流程和路由配置文件为聊天分配支持代理。
来自代理的消息通过 WebSocket 连接发出。移动应用程序监听 WebSocket 以接收和显示来自代理的消息，并向客户发送回消息。

先决条件

要将 Amazon Connect 聊天与移动应用程序集成，您必须具备以下先决条件：

创建 Amazon Connect 实例.

—或者—

如果您有 Connect 实例，请按照以下步骤为该实例启用聊天。 GitHub
创建 Amazon Connect 联系流程，随时可以接收聊天联系人。
- 记下实例 ID。
- 找到 contactFlowId适合的入站流示例（首次联系体验）.
部署自定义 Amazon Connect 聊天后端。请参阅上的 startChatContactAPI 模板 GitHub。
- 部署 startChatContactLambda 函数 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，它会返回建立连接所需的 WebSocket 网址。

以下示例说明如何为 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()
    }

以下示例展示了如何为 Android 建立连接：


// 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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

解决通信小部件的问题

创建快速响应