本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在 Amazon Connect 中启用实时聊天消息流 Amazon Connect Chat 提供的[APIs](https://docs.aws.amazon.com/connect/latest/APIReference/Welcome.html)功能使您能够订阅聊天消息的实时流。使用这些 APIs，您可以： + 在创建新的聊天联系人时，实时流式传输聊天消息。 + 扩展当前的 Amazon Connect Chat 功能，以支持与 SMS 解决方案和第三方消息应用程序的集成、启用移动推送通知以及创建分析控制面板来监控和跟踪聊天消息活动等应用场景。 **注意** 本页介绍如何订阅 SNS 终端节点，以便在 Amazon Connect 中实时传输聊天消息。如果您正在尝试在 Amazon Connect 中为对话式 AI 互动启用消息流，请参阅[为 AI 支持的聊天启用消息流](message-streaming-ai-chat.md)。 ## 消息流 APIs 的工作原理 当 [Amazon Connect 聊天联系 APIs人中发生某些事件时，就会触发 Amazon Connect 消息流](https://docs.aws.amazon.com/connect/latest/APIReference/Welcome.html)。例如，当客户发送新的聊天消息时，该事件会向指定端点发送一个[有效负载](sns-payload.md)，其中包含有关刚刚发送的消息的数据。消息通过 [Amazon Simple Notification Service](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) (Amazon SNS) 发布到特定端点。 本主题将介绍如何使用 Amazon Connect 和 Amazon SNS 设置实时消息流。步骤如下： 1. 使用 Amazon SNS 控制台创建一个新的标准 SNS 主题并设置消息。 1. 调用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 启动聊天联系。 1. 调用 [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html)API 启动消息流。 1. 调用 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)API 来创建参与者的连接。 ## 第 1 步：创建一个标准的 SNS 主题 1. 转到 Amazon SNS 控制台。 1. 在您的 AWS 账户@@ [中创建 SNS 主题](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html)。在**详细信息**部分的**类型**中，选择**标准**，输入主题名称，然后选择**创建主题**。 **注意** 当前，消息流 APIs 仅支持用于消息实时流式传输的标准 SNS。它们不支持 [Amazon SNS FIFO（先进先出）主题](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)。 1. 创建主题后，其 Amazon 资源名称 (ARN) 会在**详细信息**部分中显示。将主题 ARN 复制到剪贴板。您将在下一步和 [第 3 步：对联系启用消息流](#step3-chat-streaming) 中使用主题 ARN。 主题 ARM 与以下示例类似： ``` arn:aws:sns:us-east-1:123456789012:MyTopic ``` 1. 选择**访问策略**选项卡，选择**编辑**，然后在 SNS 主题上添加基于资源的策略，这样 Amazon Connect 就有权向其发布内容了。以下是 SNS 策略示例，您可以将其复制粘贴到 JSON 编辑器中，然后使用自己的值进行自定义： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"connect.amazonaws.com" }, "Action":"sns:Publish", "Resource":"arn:aws:sns:us-east-1:111122223333:TopicName", "Condition":{ "StringEquals":{ "aws:SourceAccount":"111122223333" }, "ArnEquals":{ "aws:SourceArn":"arn:aws:connect:us-east-1:111122223333:instance/InstanceId" } } } ] } ``` ------ **注意** 默认**访问策略**附带适用于 `sourceOwner` 的条件，例如： ``` "Condition": { "StringEquals": { "AWS:SourceOwner": "921772911154" } } ``` 请务必将其移除并替换为 `SourceAccount`，例如： ``` "Condition":{ "StringEquals":{ "aws:SourceAccount":"YOUR_AWS_ACCOUNT_ID" }, "ArnEquals":{ "aws:SourceArn":"YOUR_CONNECT_INSTANCE_ARN" } } ``` 这样可以防止出现[跨服务混淆座席](cross-service-confused-deputy-prevention.md)的问题。 1. 如果您要在 SNS 上使用服务器端加密，请确认您已在 KMS key上启用了 `connect.amazonaws.com` 权限。以下是策略示例： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "key-consolepolicy-3", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root", "Service": "connect.amazonaws.com" }, "Action": "kms:*", "Resource": "*" }, { "Sid": "Allow access for Key Administrators", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root", "Service": "connect.amazonaws.com" }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" } ] } ``` ------ ## 第 2 步：启用聊天联系 1. 调用 Amazon Connect [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 发起聊天联系。 有关如何创建用于调用 Amazon Connect 的软件开发工具包客户端的信息 APIs，请参阅以下主题： + [班级 AmazonConnectClientBuilder](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/connect/AmazonConnectClientBuilder.html) + [创建服务客户端](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/creating-clients.html) 1. 跟踪[StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)响应，因为这些响应属性用于呼叫启用直播 APIs 所需的其他聊天。`ContactId` `ParticipantToken`这将在接下来的步骤中进行说明。 ## 第 3 步：对联系启用消息流 + 致电[StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html)以启用对您的 SNS 主题的实时消息流式传输。 + **限制**：每位联系人最多可以订阅两个 SNS 主题。 + 致电时 [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html)，您需要提供 SNS 主题的 Amazon 资源名称 (ARN)（请参阅）。[第 1 步：创建一个标准的 SNS 主题](#step1-chat-streaming) 一个 SNS 主题 ARN 可以跨 AWS 账户多个使用，但它必须与您的 Amazon Connect 实例位于同一个区域。例如，如果您的主题 ARN 位于 **us-east-1**，您的 Amazon Connect 实例也必须位于 **us-east-1**。 + 对于在直播端点上未收到的初始聊天消息，您可以调用 [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html)API 来接收初始消息。 ## 第 4 步：创建参与者连接 + [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)使用传递`ConnectParticipant`为 true 的属性进行调用。 + 您必须在创建聊天[CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)后的五分钟内致电。 + 只有在[第 2 步：启用聊天联系](#step2-chat-streaming)您启用了直播功能[CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)且来电者参与者启用时，才可以在`ConnectParticipant`设置为 true 的情况下进行通话`Customer`。 + 如果您已经使用 `WEBSOCKET` 成功连接到聊天联系，则此步骤（创建参与者连接）为可选。 ## 后续步骤 你已经准备好处理消息流 APIs了。 1. 要验证它是否正常运行，请检查消息是否已发布到您创建的 SNS 主题。您可以使用 Amazon CloudWatch 指标来做到这一点。有关说明，请参阅使用[监控 Amazon SNS 主题](https://docs.aws.amazon.com/sns/latest/dg/sns-monitoring-using-cloudwatch.html)。 CloudWatch 1. 由于 SNS 的[保留期有限](https://aws.amazon.com/blogs//aws/sns-ttl-control/)，建议您设置 [Amazon Simple Queue Service (Amazon SQS)](https://aws.amazon.com/sqs/)、[Amazon Kinesis](https://aws.amazon.com/kinesis/) 或其他服务来保留消息。 1. 使用[StopContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StopContactStreaming.html)是可选的，如果聊天通过联系流[断开连接](disconnect-hang-up.md)，或者客户断开了聊天，则不需要使用。不过，`StopContactStreaming` 提供了即使聊天正在进行，也能中止 SNS 主题消息流的选项。 # 在 Amazon Connect 中启用消息流后，使用 Amazon SNS 有效载荷 成功启用消息流后，您可能需要筛选消息，以便将其发送给目标参与者：座席、客户或所有人。 要按参与者进行筛选，请阅读 SNS 标题的特定属性 `MessageVisibility`，以确定该消息是仅限客户、仅限座席还是发送给所有人。 + 仅发送给客户：对于面向客户的所有代码，客户端需要筛选出发送给客户的消息，并建立以下逻辑将消息转发给他们。 ``` if ( ( MessageVisibility == CUSTOMER || MessageVisibility == ALL) && ParticipantRole != CUSTOMER ) ``` + 仅发送给座席： ``` if ( ( MessageVisibility == AGENT || MessageVisibility == ALL) && ParticipantRole != AGENT ) ``` 您还可以通过构建自定义[订阅筛选策略](https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html)来利用 Amazon SNS 中的筛选功能。这会将消息筛选逻辑从 SNS 主题订阅者转移到 SNS 服务本身。 ## 有效负载中的消息属性 以下是对 Amazon SNS 有效负载中每个消息属性的说明： + `InitialContactId`：聊天的初始联系 ID。 + `ContactId`：聊天的当前联系 ID。如果聊天或 queue-to-queue联系流程中有新的代理，则`InitialContactId`和`ContactId`可能会有所不同。 + `ParticipantRole`：发送消息的参与者。 + `InstanceId`：Amazon Connect 实例 ID。 + `AccountId`: AWS 账户 ID。 + `Type`：可能的值：`EVENT`、`MESSAGE`。 + `ContentType`：可能的值：`application/vnd.amazonaws.connect.event.typing`、`application/vnd.amazonaws.connect.event.participant.joined`、`application/vnd.amazonaws.connect.event.participant.left`、`application/vnd.amazonaws.connect.event.transfer.succeeded`、`application/vnd.amazonaws.connect.event.transfer.failed`、`application/vnd.amazonaws.connect.message.interactive`、`application/vnd.amazonaws.connect.event.chat.ended` 等。 + `MessageVisibility`：可能的值：`AGENT`、`CUSTOMER`、`ALL`。 ## SNS 有效负载示例 ``` { "Type" : "Notification", "MessageId" : "ccccccccc-cccc-cccc-cccc-ccccccccccccc", "TopicArn" : "arn:aws:sns:us-west-2:009969138378:connector-svc-test", "Message" : "{\"AbsoluteTime\":\"2021-09-08T13:28:24.656Z\",\"Content\":\"help\",\"ContentType\":\"text/plain\",\"Id\":\"333333333-be0d-4a44-889d-d2a86fc06f0c\",\"Type\":\"MESSAGE\",\"ParticipantId\":\"bbbbbbbb-c562-4d95-b76c-dcbca8b4b5f7\",\"DisplayName\":\"Jane\",\"ParticipantRole\":\"CUSTOMER\",\"InitialContactId\":\"33333333-abc5-46db-9ad5-d772559ab556\",\"ContactId\":\"33333333-abc5-46db-9ad5-d772559ab556\"}", "Timestamp" : "2021-09-08T13:28:24.860Z", "SignatureVersion" : "1", "Signature" : "examplegggggg/1tEBYdiVDgJgBoJUniUFcArLFGfg5JCvpOr/v6LPCHiD7A0BWy8+ZOnGTmOjBMn80U9jSzYhKbHDbQHaNYTo9sRyQA31JtHHiIseQeMfTDpcaAXqfs8hdIXq4XZaJYqDFqosfbvh56VPh5QgmeHTltTc7eOZBUwnt/177eOTLTt2yB0ItMV3NAYuE1Tdxya1lLYZQUIMxETTVcRAZkDIu8TbRZC9a00q2RQVjXhDaU3k+tL+kk85syW/2ryjjkDYoUb+dyRGkqMy4aKA22UpfidOtdAZ/GGtXaXSKBqazZTEUuSEzt0duLtFntQiYJanU05gtDig==", "SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-11111111111111111111111111111111.pem", "UnsubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-west-2:000000000000:connector-svc-test:22222222-aaaa-bbbb-cccc-333333333333", "MessageAttributes" : { "InitialContactId" : {"Type":"String","Value":"33333333-abc5-46db-9ad5-d772559ab556"}, "MessageVisibility" : {"Type":"String","Value":"ALL"}, "Type" : {"Type":"String","Value":"MESSAGE"}, "AccountId" : {"Type":"String","Value":"999999999999"}, "ContentType" : {"Type":"String","Value":"text/plain"}, "InstanceId" : {"Type":"String","Value":"dddddddd-b64e-40c5-921b-109fd92499ae"}, "ContactId" : {"Type":"String","Value":"33333333-abc5-46db-9ad5-d772559ab556"}, "ParticipantRole" : {"Type":"String","Value":"CUSTOMER"} } } ``` # 排除 Amazon Connect 中消息流的问题 ## 消息未发布到 SNS 发生这种情况时，建议您检查 [第 1 步：创建一个标准的 SNS 主题](chat-message-streaming.md#step1-chat-streaming) 中的信息： + 确保您使用的是标准 SNS，而不是 [Amazon SNS FIFO（先进先出）](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)。当前，消息流仅 APIs 支持标准 SNS 来实现消息的实时流式传输。 + 确保在您的账户中正确应用了基于 SNS 资源的权限。 + 如果启用了服务器端加密，则需要向同一个 Amazon Connect 服务主体授予加密和解密权限。 ## 流式传输无法启动 如果您使用消息流 APIs 来代替 websockets，请发送连接确认事件；请参阅。[第 4 步：创建参与者连接](chat-message-streaming.md#step4-chat-streaming)这等同于连接到 Websocket。只有在连接确认事件发生后，流式传输才会开始。 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)之后拨打[StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html)以标记`Customer`为已连接；请参阅[第 3 步：对联系启用消息流](chat-message-streaming.md#step3-chat-streaming)。这样可以确保在您确认客户已准备好接收消息后发送消息。 ## 问题仍未解决？ 如果在尝试了之前的解决方案后仍然存在消息流问题，请联系 支持 寻求帮助。 Amazon Connect 管理员可以选择以下选项之一联系支持人员： + 如果您有 AWS 支持帐户，请前往[支持中心](https://console.aws.amazon.com/support/home)并提交工单。 + 否则，请打开 [AWS 管理控制台](https://console.aws.amazon.com/) 并依次选择**Amazon Connect**、**支持**、**创建案例**。 提供以下信息会很有帮助： + 您的联络中心实例 ID/ARN。要查找您的实例 ARN，请参阅 [找到您的 Amazon Connect 实例 ID 或 ARN](find-instance-arn.md)。 + 您所在区域。 + 问题的详细说明。