本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 Amazon Connect 中设置客户聊天体验
<a name="enable-chat-in-app"></a>

您可以使用以下方法之一为您的客户提供聊天体验：
+ [在 Amazon Connect 托管的网站上添加聊天用户界面](add-chat-to-website.md). 
+ [使用 Amazon Connect 开源示例自定义聊天内容](download-chat-example.md). 
+ [使用 Amazon Connect 自定义您的解决方案 APIs](integrate-with-startchatcontact-api.md)。建议您在自定义自己的聊天体验时从 Amazon Connect ChatJS 开源库开始。有关更多信息，请参阅 GitHub 上的 [Amazon Connect ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs) repo。

## 更多自定义聊天体验的资源
<a name="more-resource-customize-chat"></a>
+ 交互式消息为客户提供了提示和预先配置的显示选项，供他们选择。这些消息由 Amazon Lex 提供支持，并使用 Lambda 通过 Amazon Lex 进行配置。有关如何通过 Amazon Lex 添加交互式消息的说明，请参阅此博客：[为您的 Amazon Connect 聊天自动程序设置交互式消息](https://aws.amazon.com/blogs/contact-center/easily-set-up-interactive-messages-for-your-amazon-connect-chatbot/)。

  Amazon Connect 支持以下模板：列表选择器和时间选取器。有关更多信息，请参阅 [在聊天中为客户添加 Amazon Lex 互动消息](interactive-messages.md)。
+  [通过 Amazon Connect 启用 Apple Messages for Business](apple-messages-for-business.md) 
+  [Amazon Connect 服务 API 文档](https://docs.aws.amazon.com/connect/latest/APIReference)，尤其是 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API。
+  [Amazon Connect 参与者服务 API](https://docs.aws.amazon.com/connect-participant/latest/APIReference/Welcome.html)。
+  [Amazon Connect 聊天 SDK 和示例实施](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/) 
+  [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams)。用于将现有应用与 Amazon Connect 集成。您可以将联系人控制面板 (CCP) 组件嵌入到应用中。
+  [为 AI 支持的聊天启用消息流](message-streaming-ai-chat.md) 

# Amazon Connect 中的 chat/SMS 频道
<a name="web-and-mobile-chat"></a>

**重要**  
**尝试联系 Amazon 寻求支持？** 参见 [Amazon Customer Service](https://www.amazon.com/gp/help/customer/display.html?icmpid=docs_connect_messagingcap_customerservice)（Amazon 订单和配送）或 [AWS 支持](https://aws.amazon.com/premiumsupport/?icmpid=docs_connect_messagingcap_premiumsupport)（Amazon Web Services）。

Amazon Connect 允许您在网站和移动应用中内置聊天消息收发功能（移动聊天、网络聊天、短信和第三方消息收发服务）。它使您的客户能够通过任何业务应用程序、网络或移动设备开始与联络中心座席聊天。

交互是异步的，客户可以开始与座席或 Amazon Lex 自动程序聊天，再离开，然后再次恢复对话。他们甚至可以切换设备再继续聊天。

**Topics**
+ [多种渠道，一种体验](#unified-experience-chat)
+ [开始使用](#enable-chat)
+ [聊天场景示例](#example-chat-scenario)
+ [聊天何时结束？](#when-do-chats-end)
+ [定价](#web-and-mobile-chat-pricing)
+ [更多信息](#chat-more-info)

## 多种渠道，一种体验
<a name="unified-experience-chat"></a>

座席可以从一个用户界面帮助客户使用语音、聊天和任务。这减少了座席需要学习的工具数量以及需要交互的屏幕数量。

聊天活动可集成到您现有的联络中心流和您为语音构建的自动化系统中。您只需构建一次流，即可在多个渠道中重复使用。

您自动构建的指标收集和控制面板可受益于跨多个渠道的统一指标。

## 开始使用
<a name="enable-chat"></a>

要向您的 Amazon Connect 联络中心添加聊天消息收发功能并允许您的座席参与聊天，请执行以下步骤：
+ [创建用于存储聊天记录的 Amazon S3 存储桶](amazon-connect-instances.md#get-started-data-storage)时，会在实例级别启用聊天。
+ [将聊天添加到座席的路由配置文件中](routing-profiles.md)。
+ 或者，也可以设置聊天子类型，例如短信。您可以通过使用获取支持 SMS 的电话号码 AWS End User Messaging SMS，将其导入 Amazon Connect，然后将其分配给您的流程。有关更多信息，请参阅: 
  + [通过以下方式申请支持短信功能的电话号码 AWS End User Messaging SMS](sms-number.md)
  + [在 Amazon Connect 中设置短信消息](setup-sms-messaging.md)

然后，座席就可以通过联系人控制面板开始接受聊天。

您可以将聊天消息渠道的实时和历史指标（例如到达时间、处理时间）视为聊天频道整体指标的一部分，这与用于calls/chats/tasks评估客服表现和工作效率的报告体验相同。

Amazon Connect 提供了一些资源来帮助您在网站上添加聊天功能。有关更多信息，请参阅 [在 Amazon Connect 中设置客户聊天体验](enable-chat-in-app.md)。

## 聊天场景示例
<a name="example-chat-scenario"></a>

客户和座席正在聊天。客户不再回复座席。座席问：“您还在吗？” 没有得到回复。座席离开聊天。现在开始，聊天不再与座席关联。您的流决定了接下来会发生什么。

在此场景中，假设客户后来发送了另一条消息（“嘿，我回来了”），然后聊天恢复。根据您在流中定义的逻辑，聊天可以分配给原始座席或其他的座席/队列。

下面为您介绍如何构建此场景：

1. 创建断开连接流。下图显示了流设计器中的 [Amazon Connect 中的断开连接流示例](sample-disconnect.md)。此流程包括以下数据块：**播放提示**、**等待**，分支到三个**播放提示**（**客户已返回**、**时间已过期**和**错误**），然后**转移到队列**和**断开连接**。  
![\[示例断开连接流。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/sample-disconnect-flow.png)

1.  在断开连接流中，添加一个[等待](wait.md)数据块。“等待”数据块具有两个分支：
   +  **超时**：如果客户在指定时间后未发送消息，则运行此分支。聊天的总持续时间（包括多个**等待**数据块）不能超过 7 天。

      例如，对于此分支，您可能只想运行**断开连接**数据块并结束聊天。
   +  **客户返回**：在客户返回并发送消息时运行此分支。使用此分支，您可以将客户路由到以前的座席、以前的队列，或者设置新的工作队列/座席。

1.  在入站流中，添加[设置断开连接流](set-disconnect-flow.md)数据块。使用它指定当座席或 Amazon Lex 自动程序已与聊天断开连接且只有客户留下时，应运行“设置断开连接流”。

    例如，在以下数据块中，我们指定应运行**示例断开连接流**。  
![\[设置断开连接流数据块、选择流下拉菜单、示例断开连接流选项。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/set-disconnect-flow.png)

    有关使用**设置断开连接流**数据块的示例，请参阅 [入站流示例](sample-inbound-flow.md)。

## 聊天何时结束？
<a name="when-do-chats-end"></a>

 默认情况下，聊天对话的总持续时间（包括客户不活跃时等待的时间）不能超过 25 小时。但是，您可以更改此默认时长，配置自定义聊天时长。您可以将聊天配置为最短 1 小时（60 分钟）至最长 7 天（10,080 分钟）。要配置自定义聊天时长，请调用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 并添加`ChatDurationInMinutes`参数。

在正在进行的聊天会话中，客户离开并重新加入现有正在进行的聊天会话的次数没有限制。要完成此操作，请使用[等待](wait.md)数据块。例如，在结束聊天会话之前，您可能会等待 12 个小时让客户恢复聊天。如果客户在 12 小时后尝试恢复聊天，在流中，您可以让 Amazon Lex 自动程序询问他们是就同一问题还是不同问题联系您。

通过指定一个明显短于聊天时长的等待时间，可以帮助确保客户获得良好的体验。例如，对于持续时间为 25 小时的聊天，客户可能在 24 小时 58 分钟时恢复聊天，但因为对话限制为在 25 小时时自动结束，因此会两分钟后被中断。

**提示**  
如果您在聊天中使用 Amazon Lex，请注意，Amazon Lex 会话的默认超时时间为 5 分钟。会话的总持续时间不能超过 24 小时。要更改会话超时，请参阅《Amazon Lex 开发人员指南》**中的[设置会话超时](https://docs.aws.amazon.com/lex/latest/dg/context-mgmt.html#context-mgmt-session-timeoutg)。

## 定价
<a name="web-and-mobile-chat-pricing"></a>

聊天按次收费。无需预付款、长租或最低月费。无论使用聊天消息的座席或客户数量如何，您都需要为每条聊天消息付费。不同的区域定价可能会有所不同。有关更多信息，请参阅 [Amazon Connect 定价](https://aws.amazon.com/connect/pricing/)。

## 更多信息
<a name="chat-more-info"></a>

有关聊天的更多信息，请参阅以下主题：
+  [在 Amazon Connect 中测试语音、聊天和任务体验](chat-testing.md) 
+  [路由如何与多个渠道一起工作](about-routing.md#routing-profile-channels-works) 
+  [在 Amazon Connect 中创建路由配置文件，将队列链接到座席](routing-profiles.md) 
+  [Amazon Connect 聊天 SDK 和示例实施](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/) 

# 在 Amazon Connect 托管的网站上添加聊天用户界面
<a name="add-chat-to-website"></a>

要通过聊天为客户提供支持，您可以在网站上添加由 Amazon Connect 托管的通信小部件。你可以在 Amazon Connect 管理网站中配置通信小部件。您可以自定义字体和颜色，并保护小部件，使其只能从您的网站启动。完成后，您就可以在网站上添加一个简短的代码片段。

由于小组件是由 Amazon Connect 托管的，这确保了您的网站上始终可以运行最新版本。

**提示**  
通信小部件的使用受默认服务限额的限制，例如每条消息所需的字符数。在将通信小部件投入生产环境之前，请确保服务限额的设置符合您组织的需求。有关更多信息，请参阅 [Amazon Connect 服务配额](amazon-connect-service-limits.md)。

**Topics**
+ [可自定义的受支持小部件片段字段](supported-snippet-fields.md)
+ [支持的浏览器](#chat-widget-supported-browsers)
+ [第 1 步：自定义您的通信小部件](#customize-chat-widget)
+ [第 2 步：指定您希望在其中显示通信小部件的网站域](#chat-widget-domains)
+ [第 3 步：确认并复制通信小部件代码和安全密钥](#confirm-and-copy-chat-widget-script)
+ [收到错误消息？](#chat-widget-error-messages)
+ [自定义小部件启动行为和按钮图标](customize-widget-launch.md)
+ [传递客户显示名称](pass-display-name-chat.md)
+ [传递联系属性](pass-contact-attributes-chat.md)
+ [针对您的聊天小部件的额外自定义](pass-customization-object.md)
+ [下载您的聊天小部件的转录](chat-widget-download-transcript.md)
+ [下载并自定义我们的开源示例](download-chat-example.md)
+ [使用 Amazon Connect 在您的应用程序中开始聊天 APIs](integrate-with-startchatcontact-api.md)
+ [聊天消息到达时向客户发送浏览器通知](browser-notifications-chat.md)
+ [通过编程方式断开聊天连接](programmatic-chat-disconnect.md)
+ [传递自定义属性以覆盖通信小部件中的默认属性](pass-custom-styles.md)
+ [用 CSS/ 瞄准你的控件按钮和框架 JavaScript](target-widget-button.md)
+ [解决通信小部件的问题](ts-cw.md)
+ [添加联系前表单或聊天前表单](add-precontact-form.md)
+ [聊天后调查](enable-post-chat-survey.md)

# Amazon Connect 中支持可自定义的小部件片段字段
<a name="supported-snippet-fields"></a>

下表列出了可以自定义的通信小部件片段字段。表格之后的代码示例显示了如何使用片段字段。


| 片段字段 | Type | 说明 | 其他文档 | 
| --- | --- | --- | --- | 
| `snippetId` | 字符串 | 必填，自动生成 | 不适用 | 
| `styles` | 字符串 | 必填，自动生成 | 不适用 | 
| `supportedMessagingContentTypes` | 数组 | 必填，自动生成 | 不适用 | 
| `customLaunchBehavior` | 对象 | 自定义您的网站呈现和启动托管小部件图标的方式 | 此主题后面的[为托管在 Amazon Connect 的网站自定义小部件启动行为和按钮图标](customize-widget-launch.md) | 
| `authenticate` | 函数 | 在您的网站上启用 JWT 安全功能的回调函数 | 此部分前面的[第 2 步：指定您希望在其中显示通信小部件的网站域](add-chat-to-website.md#chat-widget-domains)。 | 
| `customerDisplayName` | 函数 | 初始化联系人时传递客户显示名称 | 此部分后面的[在 Amazon Connect 聊天开始时传递客户显示名称](pass-display-name-chat.md)。 | 
| `customStyles` | 对象 | 覆盖默认 CSS 样式 | 此部分后面的[传递自定义属性以覆盖 Amazon Connect 中的通信小部件中的默认属性](pass-custom-styles.md)。 | 
| `chatDurationInMinutes` | 数字 | 新开始的聊天会话的总时长 | 默认值：1500 - 最小 60，最大：10080 | 
| `enableLogs` | 布尔值 | 启用调试日志 | 默认：false | 
| `language` | 字符串 |  Amazon Connect 可以对支持的 ISO-639 格式语言代码进行翻译。欲了解更多信息，请参阅 [https://en.wikipedia。 org/wiki/List\$1of\$1iso\$1639-1\$1codes。](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 这样不会翻译自定义文本覆盖和消息内容（包括已发送和已接收内容）。  | 默认语言：en\$1US。支持的语言：“cs\$1CZ”、“da\$1DK”、“de\$1DE”、“en\$1AU”、“en\$1CA”、“en\$1GB”、“en\$1US”、“es\$1ES”、“fi\$1FI”、“fr\$1FR”、“hu\$1HU”、“id\$1ID”、“it\$1IT”、“ja\$1JP”、“ko\$1KR”、“nl\$1NL”、“nn\$1NO”、“pt\$1BR”、“pt\$1PT”、“sk\$1SK”、“sv\$1SE”、“zh\$1CN”、“zh\$1TW” | 
| `disableCSM` | 布尔值 | 禁止从通信小部件跟踪客户端指标。 | 默认：false | 
| `nonce` | 字符串 | iframe 与客户网站 csp 策略之间的握手值。示例：客户 csp 允许使用 1234 随机数值，引入另一个脚本的 iframe 必须具有相同的 1234 随机数值，这样浏览器才能知道它是 iframe 父站点的可信脚本。 | 默认值：未定义 | 
| `customizationObject` | 对象 | 自定义小部件布局和脚本 | 有关更多信息，请参阅此部分后面的[针对您的 Amazon Connect 聊天小部件的额外自定义](pass-customization-object.md)。 | 
| `contactAttributes` | 对象 | 无需任何 JWT 设置，直接从片段代码向联系人流传递属性 | 有关更多信息，请参阅[聊天初始化时传递联系属性](https://docs.aws.amazon.com/connect/latest/adminguide/pass-contact-attributes-chat.html)。 | 
| `customDisplayNames` | 对象 | 覆盖 Amazon Connect 管理员网站中设置的系统或机器人显示名称和徽标配置。 | 有关更多信息，请参阅[如何传递通信小部件的覆盖系统和机器人显示的名称和徽标](https://docs.aws.amazon.com/connect/latest/adminguide/pass-custom-styles.html#pass-override-system)。 | 
| `contactMetadataHandler` | 函数 | 访问 contactId 的回拨函数。例如，添加事件侦听器来处理诸如在浏览器标签页关闭时使用 contactID 调用 StopContact 函数或使用之前的 ContactID 保持聊天持久性等场景。 |  | 
| `registerCallback` | 对象 | 这允许对公开的生命周期活动执行回拨。 有关更多信息，请参阅 [amazon-connect-chatjs](https://github.com/amazon-connect/amazon-connect-chatjs)。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/supported-snippet-fields.html) | 
| `initialMessage` | 字符串 | 要发送到新建聊天室的消息。长度限制：最小为 1，最大为 1024。 | 要使用初始消息调用联系流中配置的 Lex 机器人，请通过选择[使用信息初始化机器人](get-customer-input.md)选项来**修改获取客户输入流块**。有关更多信息，请参阅[如何配置获取客户输入流块](get-customer-input.md#get-customer-input-properties)。 | 
| `authenticationParameters` | 对象 | 这样会启用[验证客户身份](authenticate-customer.md)流数据块 | 有关更多信息，请参阅 [启用客户身份验证](enable-connect-managed-auth.md)。 | 
| `mockLexBotTyping` | 布尔值 | 为 Lex 机器人消息启用模拟键入指示器。 | 默认：false | 
| `customStartChat` | 函数 | 回调函数，用于从后端调用 Start Chat API。 | 有关更多信息，请参阅[具有自定义 Start Chat API 的托管小部件 UI](https://github.com/amazon-connect/amazon-connect-chat-interface#option-3-hosted-widget-ui-with-custom-start-chat-api)  | 

以下示例演示了如何向将聊天小部件添加到网站的 HTML 脚本中添加片段字段。

```
(function(w, d, x, id) {   /* ... */})(window, document, 
'amazon_connect', 'widgetId');
 amazon_connect('snippetId', 'snippetId');
 amazon_connect('styles', /* ... */);
 amazon_connect('registerCallback', {
    // Custom event example
    // WIDGET_FRAME_CLOSED
    /**
     * This event is triggered when user clicks on the chat widget close button, 
     * either widget close button was clicked when error in the chat session or normally by the user. 
     * This event can be used for webview use cases to go back to main app
     * 
     * @param {string} status - The reason for widget closure
     *   - "error_chat": Indicates the user clicked on widget close button due to an error in the chat session
     *   - "close_chat": Indicates the user clicked on widget close button normally by the user
     */
    'WIDGET_FRAME_CLOSED': (eventName, { status }) => {
        // You can implement custom logic based on the status value(error_chat or close_chat)
        if (status == "error_chat") {
            // handle error chat
        } else if (status == "close_chat") {
            // handle close chat  
        } 
    },
    // System event example
    /**
     * chatDetails: { 
     *     contactId: string, 
     *     participantId: string,
     *     participantToken: string,
     * }
     * data: {
     *     AbsoluteTime?: string,
     *     ContentType?: string,
     *     Type?: string,
     *     ParticipantId?: string,
     *     DisplayName?: string,
     *     ParticipantRole?: string,
     *     InitialContactId?: string
     * }
     */
    'PARTICIPANT_JOINED': (eventName, { chatDetails, data }) => {
        alert(`${data.ParticipantRole} joined the chat.`);
    },
    'event_Name_3': callback(function),
    'event_Name_4': callback(function),
    // ...
}); 
amazon_connect('initialMessage', 'Your initial message string');
// ... 
amazon_connect('snippetFieldHere', /* ... */);
<script/>
```

## 支持的浏览器
<a name="chat-widget-supported-browsers"></a>

预置的通信小部件支持以下浏览器版本及更高版本：
+ Google Chrome 85.0
+ Safari 13.1
+ Microsoft Edge version 85
+ Mozilla Firefox 81.0

通信小部件支持桌面设备的浏览器通知。有关更多信息，请参阅 [聊天消息到达时向客户发送浏览器通知](browser-notifications-chat.md)。

## 第 1 步：自定义您的通信小部件
<a name="customize-chat-widget"></a>

在此步骤中，您将为客户自定义通信小部件的体验。

1. 登录 Amazon Connect 管理员网站 https://*instance name*.my.connect.aws/。选择**自定义通信小部件**。  
![\[“配置指南”页面，“自定义通信小部件”链接。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-customize-chat-window-button.png)

1. 在**通信小部件**页面上，选择**添加通信小部件**，开始自定义新的通信小部件体验。要编辑、删除或复制现有的通信小部件，请从**操作**列下的选项中进行选择，如下图所示。  
![\[“通信小部件”页面，“添加通信小部件按钮”链接。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-add-chat-widget.png)

1. 输入通信小部件的**名称**和**描述**。
**注意**  
在 Amazon Connect 实例中创建的每个通信小部件的名称都必须是唯一的。

1. 在**通信选项**部分，选择客户如何与您的小部件互动，然后选择**保存并继续**。
**注意**  
只有在未启用聊天和语音功能的情况下，您才能启用任务或电子邮件联系前表单。

   下图显示了为客户启用聊天、消息回执和创建聊天前表单的选项。要启用聊天前表单，必须先创建一个带有连接操作按钮的[视图](view-resources-sg.md)，然后选择 `StartChatContact` 操作。有关聊天前和联系前表单的更多信息，请参阅[将 Amazon Connect 小部件添加到您的网站](connect-widget-on-website.md)。  
![\[为聊天和网络通话配置的通信小部件页面。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/comm-widget-page-chat.png)

1. 在**创建通信小部件**页面上，选择小部件按钮样式以及显示名称和样式。

   当您选择这些选项时，小部件预览会自动更新，以便您看到客户的体验效果。  
![\[通信小部件的预览。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/netra-chat-preview.png)

**按钮样式**

1. 通过输入十六进制值（[HTML 颜色代码](https://htmlcolorcodes.com/)）来选择按钮背景的颜色。

1. 选择**白色**或**黑色**作为图标颜色。无法自定义图标颜色。

**小部件标题**

1. 提供标题消息和颜色以及小部件背景颜色的值。

1. **徽标 URL**：从 Amazon S3 存储桶或其他在线来源向徽标横幅插入一个 URL。
**注意**  
如果该徽标来自 Amazon S3 存储桶以外的在线来源，则自定义页面中的通信小部件预览将不会显示徽标。只有当您的页面上安装了自定义通信小部件后，徽标才会显示。

   横幅的格式必须为 .svg、.jpg 或 .png。图像可以是 280 px（宽）x 60 px（高）。任何大于这些尺寸的图像都将被缩放，以适应 280x60 徽标组件空间。

   1. 有关如何将文件（如徽标横幅等）上传到 S3 的说明，请参阅《Amazon Simple Storage Service 用户指南》**中的[上传对象](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)。

   1. 确保正确设置了图像权限，以便通信小部件访问图像。有关如何公开访问 S3 对象的信息，请参阅《设置网站访问权限》**主题中的[第 2 步：添加存储桶策略](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteAccessPermissionsReqd.html#bucket-policy-static-site)。

**聊天视图**

1.  **字体**：使用下拉菜单为通信小部件中的文本选择字体。

1. 
   + **系统消息显示名称**：键入新的显示名称以覆盖默认名称。默认为 **SYSTEM\$1MESSAGE**。
   + **自动程序消息显示名称**：键入新的显示名称以覆盖默认名称。默认为**自动程序**。
   + **文本输入占位符**：键入新的占位符文本以覆盖默认值。默认为**键入一条消息**。
   + **结束聊天按钮文本**：键入新文本以替换默认文本。默认为**结束聊天**。

1. **座席聊天气泡颜色**：通过输入十六进制值（[HTML 颜色代码](https://htmlcolorcodes.com/)）来选择座席消息气泡的颜色。

1. **客户聊天气泡颜色**：通过输入十六进制值（[HTML 颜色代码](https://htmlcolorcodes.com/)）来选择客户消息气泡的颜色。

1. 选择**保存并继续**。

## 第 2 步：指定您希望在其中显示通信小部件的网站域
<a name="chat-widget-domains"></a>

1. 输入您要放置通信小部件的网站域。聊天仅会在此步骤中选择的网站上加载。

   选择**添加域**，添加最多 50 个域。  
![\[“添加域”选项。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-add-domain.png)

   域允许列表行为：
   + 自动包括子域。例如，如果您允许 example.com，则其所有子域（例如 sub.example.com）也被允许。
   + 协议 http:// 或 https:// 必须与您的配置完全匹配。设置允许域时指定确切的协议。
   + 自动允许所有 URL 路径。例如，如果允许使用 example.com，则允许其下的所有页面（例如示例。 com/cart or example.com/checkout) 可以访问。不能允许或阻止特定的子目录。
**重要**  
仔细检查您的网站 URLs 是否有效且不包含错误。请添加以 https:// 为开头的完整 URL。
建议您在生产网站和应用程序中使用 https://。

1. 在 “**为您的通信小组件添加安全性**” 下，我们建议您选择 “**是**”，然后与您的网站管理员合作设置您的 Web 服务器，以便为新的聊天请求发放 JSON Web Token (JWTs)。这使您在发起新聊天时拥有了更多控制权，包括验证发送到 Amazon Connect 的聊天请求是否来自经过身份验证的用户的功能。  
![\[激活新通信小部件请求的安全性。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-choose-security.png)

   选择**是**，会产生以下结果：
   + Amazon Connect 在下一页提供了 44 个字符的安全密钥，你可以用它来创建 JSON 网络令牌 () JWTs。
   + Amazon Connect 在通信小部件嵌入脚本中添加了一个回调函数，用于在聊天启动时检查 JSON Web 令牌（JWT）。

     您必须在嵌入式代码段中设置回调函数，如以下示例所示。

     ```
     amazon_connect('authenticate', function(callback) {
       window.fetch('/token').then(res => {
         res.json().then(data => {
           callback(data.data);
         });
       });
     });
     ```

   如果您选择此选项，在下一步中，您将获得一个安全密钥，用于在您的网站上发起的所有聊天请求。请您的网站管理员将您的 Web 服务器设置为 JWTs 使用此安全密钥发布。

1. 选择**保存**。

## 第 3 步：确认并复制通信小部件代码和安全密钥
<a name="confirm-and-copy-chat-widget-script"></a>

在此步骤中，您要确认选择并复制通信小部件的代码，并将其嵌入到您的网站中。如果您选择在[步骤 2 JWTs ](#chat-widget-domains) 中使用，也可以复制用于创建密钥的密钥。

### 安全密钥
<a name="chat-widget-security-key"></a>

使用此 44 个字符的安全密钥从您的 Web 服务器生成 JSON 网络令牌。如果需要更改，您也可以更新或轮换密钥。当您执行此操作时，Amazon Connect 会为您提供一个新密钥，同时保留以前的密钥，直到您替换它。部署新密钥后，您可以返回 Amazon Connect 并删除之前的密钥。

![\[Amazon Connect 提供的安全密钥。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-security-key.png)


当客户与您网站上的“开始聊天”图标进行互动时，通信小部件会向 Web 服务器请求 JWT。提供 JWT 后，小部件会将其包含在最终客户向 Amazon Connect 发出的聊天请求中。然后，Amazon Connect 会使用密钥解密令牌。如果成功，则确认了 JWT 是由您的 Web 服务器发出的，Amazon Connect 会将聊天请求路由到您的联络中心座席。

#### JSON Web 令牌的详细信息
<a name="jwt"></a>
+ 算法：**HS256**
+ 声明：
  + **订阅**:*widgetId*

    将 `widgetId` 替换为您自己的 widgetId。要查找您的 widgetId，请参阅[通信小部件脚本](#chat-widget-script)中的示例。
  + **iat**：\$1按时发放。
  + **exp**：\$1有效期（最长 10 分钟）。
  + **segmentAttributes（可选）**：一组系统定义的键值对，使用属性映射存储在各个联系分段上。如需了解更多信息 SegmentAttributes ，请查看 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-SegmentAttributes)API。
  + **属性（可选）**：带有 string-to-string键值对的对象。联系人属性必须遵守 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes)API 设置的限制。
  + **relatedContactId （可选）**：带有有效联系人 ID 的字符串。 relatedContactId 必须遵守 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 设定的限制。
  + **customerId（可选）**：这可以是 Amazon Connect Customer Profiles ID，也可以是来自外部系统（例如 CRM）的自定义标识符。

  \$1有关日期格式的信息，请参阅以下互联网工程任务组 (IETF) 文档：[JSON Web 令牌 (JWT)](https://tools.ietf.org/html/rfc7519)，第 5 页。

下面的代码片段举例说明了如何使用 Python 生成 JWT：

```
import jwt 
import datetime 
CONNECT_SECRET = "your-securely-stored-jwt-secret" 
WIDGET_ID = "widget-id" 
JWT_EXP_DELTA_SECONDS = 500

payload = { 
'sub': WIDGET_ID, 
'iat': datetime.datetime.utcnow(), 
'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=JWT_EXP_DELTA_SECONDS), 
'customerId': "your-customer-id",
'relatedContactId':'your-relatedContactId',                    
'segmentAttributes': {"connect:Subtype": {"ValueString" : "connect:Guide"}}, 'attributes': {"name": "Jane", "memberID": "123456789", "email": "Jane@example.com", "isPremiumUser": "true", "age": "45"} } 
header = { 'typ': "JWT", 'alg': 'HS256' } 
encoded_token = jwt.encode((payload), CONNECT_SECRET, algorithm="HS256", headers=header) // CONNECT_SECRET is the security key provided by Amazon Connect
```

### 通信小部件脚本
<a name="chat-widget-script"></a>

下图显示了您在 JavaScript 希望客户与代理聊天的网站上嵌入的示例。该脚本会在网站右下角显示小部件。

![\[通信小部件脚本。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-code.png)


网站加载时，客户会首先看到**开始**图标。他们选择此图标后，通信小部件将打开，客户就可以向您的座席发送消息了。

要随时更改通信小部件，请选择**编辑**。

**注意**  
保存的更改将在几分钟内更新客户体验。保存之前，请确认您的小部件配置。

![\[小部件预览中的“编辑”链接。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-edit.png)


要更改网站上的小组件图标，您将收到一个新的代码片段，用于直接更新您的网站。

## 收到错误消息？
<a name="chat-widget-error-messages"></a>

如果遇到错误消息，请参阅[排查您的 Amazon Connect 通信小部件问题](ts-cw.md)。

# 为托管在 Amazon Connect 的网站自定义小部件启动行为和按钮图标
<a name="customize-widget-launch"></a>

要进一步自定义网站显示和启动托管小部件图标的方式，您可以配置启动行为并隐藏默认图标。例如，您可以通过编程方式从网站上显示的**与我们聊天**按钮元素启动小部件。

**Topics**
+ [如何为小组件配置自定义启动行为](#config-widget-launch)
+ [支持的选项和限制](#launch-options-constraints)
+ [为自定义用例配置小组件启动](#launch-usage)
+ [启用跨选项卡的聊天会话持久化](#chat-persistence-across-tabs)

## 如何为小组件配置自定义启动行为
<a name="config-widget-launch"></a>

要传递自定义启动行为，请使用以下示例代码块并将其嵌入到小部件中。以下示例中显示的所有字段均为可选字段，可以任意组合使用。

```
amazon_connect('customLaunchBehavior', {
    skipIconButtonAndAutoLaunch: true,
    alwaysHideWidgetButton: true,
    programmaticLaunch: (function(launchCallback) {
        var launchWidgetBtn = document.getElementById('launch-widget-btn');
        if (launchWidgetBtn) {
            launchWidgetBtn.addEventListener('click', launchCallback);
            window.onunload = function() {
            launchWidgetBtn.removeEventListener('click', launchCallback);
            return;
            }
        }
    })
});
```

## 支持的选项和限制
<a name="launch-options-constraints"></a>

下表列出了支持的自定义启动行为选项。均为可选字段，可任意组合使用。


| 选项名称 | Type | 说明 | 默认 值 | 
| --- | --- | --- | --- | 
|  `skipIconButtonAndAutoLaunch`  | 布尔值  | 一个标志 enable/disable ，表示无需用户点击页面加载即可自动启动小组件。 | 未定义 | 
|  `alwaysHideWidgetButton`  | 布尔值  | 用于 enable/disable 渲染控件图标按钮的标志（除非有正在进行的聊天会话）。 | 未定义 | 
|  `programmaticLaunch`  | 函数  |  | 未定义 | 

## 为自定义用例配置小组件启动
<a name="launch-usage"></a>

### 自定义小组件启动按钮
<a name="custom-launch-button"></a>

以下示例显示了您需要在小部件中做出的更改，以便将编程启动配置为仅在用户选择网站上任意位置显示的自定义按钮元素时才打开。例如，他们可以选择名为**联系我们**或**与我们聊天**的按钮。或者，您可以隐藏默认 Amazon Connect 小部件图标，直到该小部件打开为止。

```
<button id="launch-widget-btn">Chat With Us</button>
```

```
<script type="text/javascript">
 (function(w, d, x, id){
    s=d.createElement("script");
    s.src="./amazon-connect-chat-interface-client.js"
    s.async=1;
    s.id=id;
    d.getElementsByTagName("head")[0].appendChild(s);
    w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
  })(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
  amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
  amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
  amazon_connect('customLaunchBehavior', {
        skipIconButtonAndAutoLaunch: true,
        alwaysHideWidgetButton: true,
        programmaticLaunch: (function(launchCallback) {
            var launchWidgetBtn = document.getElementById('launch-widget-btn');
            if (launchWidgetBtn) {
                launchWidgetBtn.addEventListener('click', launchCallback);
                window.onunload = function() {
                launchWidgetBtn.removeEventListener('click', launchCallback);
                return;
                }
            }
        }),
    });
</script>
```

### 支持超链接
<a name="hyperlink-support"></a>

以下示例显示了您需要在小部件配置 `auto-launch` 中做出的更改，这样无需等待用户点击即可打开小部件。您可以部署到由网站托管的页面，创建可共享的超链接。

```
https://example.com/contact-us?autoLaunchMyWidget=true
```

```
<script type="text/javascript">
 (function(w, d, x, id){
    s=d.createElement("script");
    s.src="./amazon-connect-chat-interface-client.js"
    s.async=1;
    s.id=id;
    d.getElementsByTagName("head")[0].appendChild(s);
    w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
  })(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
  amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
  amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
  amazon_connect('customLaunchBehavior', {
        skipIconButtonAndAutoLaunch: true
    });
</script>
```

### 点击按钮时加载小组件资产
<a name="load-assets"></a>

以下示例显示了您需要在小部件中做出的更改，以便在用户单击**与我们聊天**按钮时通过获取小部件的静态资产来加快网站页面的加载速度。通常，只有一小部分访问**联系我们**页面的客户会打开 Amazon Connect 小部件。尽管客户从未打开过小部件，该小部件也可能会通过从 CDN 获取文件来增加页面加载的延迟。

另一种解决方案是在单击按钮时不同步（或从不）运行代码片段。

```
<button id="launch-widget-btn">Chat With Us</button>
```

```
var buttonElem = document.getElementById('launch-widget-btn');

buttonElem.addEventListener('click', function() {
    (function(w, d, x, id){
        s=d.createElement("script");
        s.src="./amazon-connect-chat-interface-client.js"
        s.async=1;
        s.id=id;
        d.getElementsByTagName("head")[0].appendChild(s);
        w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
    })(window, document, 'amazon_connect', 'asfd-asdf-asfd-asdf-asdf');
    amazon_connect('styles', { openChat: { color: '#000', backgroundColor: '#3498fe'}, closeChat: { color: '#fff', backgroundColor: '#123456'} });
    amazon_connect('snippetId', "QVFJREFsdafsdfsadfsdafasdfasdfsdafasdfz0=")
    amazon_connect('customLaunchBehavior', {
        skipIconButtonAndAutoLaunch: true
    });
});
```

### 在浏览器窗口中启动新聊天
<a name="new-chat-browser-window"></a>

以下示例显示了您需要在小部件中做出的更改，以启动一个新的浏览器窗口并在全屏模式下自动启动聊天。

```
<button id="openChatWindowButton">Launch a Chat</button>
```

```
<script> // Function to open a new browser window with specified URL and dimensions
    function openNewWindow() {
        var url = 'https://mycompany.com/support?autoLaunchChat=true';

        // Define the width and height
        var width = 300;
        var height = 540;

        // Calculate the left and top position to center the window
        var left = (window.innerWidth - width) / 2;
        var top = (window.innerHeight - height) / 2;

        // Open the new window with the specified URL, dimensions, and position
        var newWindow = window.open(url, '', 'width=${width}, height=${height}, left=${left}, top=${top}');
    }

    // Attach a click event listener to the button
    document.getElementById('openChatWindowButton').addEventListener('click', openNewWindow);
</script>
```

## 启用跨选项卡的聊天会话持久化
<a name="chat-persistence-across-tabs"></a>

默认情况下，如果用户在一个选项卡中有一个打开的聊天，然后打开一个新的选项卡并开始另一个聊天，则新聊天将开始，取代与现有聊天的连接。如果您希望用户连接在初始选项卡中启动的现有聊天，则可以启用跨选项卡的聊天会话持久化。

聊天会话被存储在浏览器上会话存储中的变量 `persistedChatSession` 内。首次初始化该小部件时，需要将此值复制到新选项卡的会话存储中。以下是操作说明。

要在用户导航到不同的子域时连接到同一个聊天会话，您可以设置 Cookie 的域属性。例如，您拥有两个子域：`domain1.example.com` 和 `domain2.example.com`。您可以添加属性 `domain=.example.com` 以便可以从所有子域访问该 Cookie。

1. 将以下代码复制到托管小部件代码段中其他 amazon\$1connect 函数旁边。这将使用 `registerCallback` 事件处理程序将 `persistedChatSession` 存储为 Cookie，以便可以在新选项卡中访问它。聊天结束时，它还会清理 Cookie。

   

   ```
   amazon_connect('registerCallback', {
   'CONNECTION_ESTABLISHED': (eventName, { chatDetails, data }) => {
    document.cookie = `activeChat=${sessionStorage.getItem("persistedChatSession")}; SameSite=None; Secure`;
   }, 
   'CHAT_ENDED': () => {
     document.cookie = "activeChat=; SameSite=None; Secure";
   }
   });
   ```

1. 检索 Cookie 值（如果存在），并在新选项卡中设置会话存储值。

   ```
   const cookie = document.cookie.split('; ').find(c => c.startsWith('activeChat='));
   if (cookie) {
     const activeChatValue = cookie.split('=')[1];
     sessionStorage.setItem('persistedChatSession', activeChatValue);
   }
   
   //Your hosted widget snippet should be on this page
   ```

# 在 Amazon Connect 聊天开始时传递客户显示名称
<a name="pass-display-name-chat"></a>

要为客户和座席提供更加个性化的体验，您可以自定义 Amazon Connect 通信小部件，以便在联系初始化期间传递客户显示名称。在整个聊天互动过程中，客户和座席都可以看到该名称。此显示名称将记录在聊天记录中。

下图显示了客户在聊天体验中显示的名称，以及他们在座席的 CCP 中的名称。

![\[客户在聊天体验中的名称，座席的 CCP 中的客户名称。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-displayname.png)


1. 客户使用聊天用户界面时看到的客户显示名称。

1. 使用 CCP 的座席看到的客户显示名称。

## 如何在通信小部件中传递客户显示名称
<a name="setup-display-name"></a>

要传递客户显示名称，请在代码段中执行回调函数。Amazon Connect 会自动检索显示名称。

1. 如果尚未执行，请完成 [在 Amazon Connect 托管的网站上添加聊天用户界面](add-chat-to-website.md) 中的步骤。

1. 扩充现有的小部件片段，添加 `customerDisplayName` 回调。它可能与下面的示例类似：

   ```
   amazon_connect('customerDisplayName', function(callback) {
     const displayName = 'Jane Doe';
     callback(displayName);
   });
   ```

   重要的是将名称传递给 `callback(name)`。

## 您需要了解的有关客户显示名称的需知事项
<a name="setup-display-name-important-notes"></a>
+ 一次只能存在一个 `customerDisplayName` 函数。
+ 客户显示名称必须遵守 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-Type-ParticipantDetails-DisplayName)API 设置的限制。也就是说，名称长度必须在 1 到 256 个字符之间。
+ 空字符串、空或未定义是显示名称的无效输入。为了防止意外传递这些输入，小部件会在浏览器控制台中记录错误 `Invalid customerDisplayName provided`，然后使用默认显示名称**客户**开始聊天。
+ 由于该片段位于网站的前端，因此请勿将敏感数据作为显示名称传递。请务必遵循适当的安全措施，以确保您的数据安全，防范攻击和恶意行为。

# 在聊天开始时，在联系人控制面板 (CCP) 中将联系属性传递给座席
<a name="pass-contact-attributes-chat"></a>

您可以使用[联系属性](what-is-a-contact-attribute.md)获取正在使用通信小部件的联系人的相关信息。然后，您可以通过联系人控制面板 (CCP) 向座席显示该信息，或者在流中的其他地方使用这些信息。

例如，您可以自定义流，在欢迎消息中写上客户的名称。或者，您可以使用企业特有的属性 account/member IDs，例如姓名和电子邮件等客户标识符，或与联系人关联的其他元数据。

## 如何将联系属性传递到通信小部件
<a name="how-to-contact-attributes-chatwidget"></a>

1. 如[在 Amazon Connect 托管的网站上添加聊天用户界面](add-chat-to-website.md)所述，在通信小部件中启用安全保护（如果尚未启用）：

   1. 在第 2 步中，在**为聊天小部件添加安全保护**下，选择**是**。

   1. 在第 3 步中，使用安全密钥生成 JSON Web 令牌。

1. 将联系属性作为 `attributes` 声明添加到 JWT 的有效载荷中。

   以下是如何用 Python 生成带有联系属性的 JWT 的示例：
**注意**  
应先安装 JWT。要安装它，请在终端运行 `pip install PyJWT`。

   ```
   import jwt 
   import datetime 
   CONNECT_SECRET = "your-securely-stored-jwt-secret" 
   WIDGET_ID = "widget-id" 
   JWT_EXP_DELTA_SECONDS = 500
   
   payload = { 
   'sub': WIDGET_ID, 
   'iat': datetime.datetime.utcnow(), 
   'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=JWT_EXP_DELTA_SECONDS), 
   'segmentAttributes': {"connect:Subtype": {"ValueString" : "connect:Guide"}}, 'attributes': {"name": "Jane", "memberID": "123456789", "email": "Jane@example.com", "isPremiumUser": "true", "age": "45"} } 
   header = { 'typ': "JWT", 'alg': 'HS256' } 
   encoded_token = jwt.encode((payload), CONNECT_SECRET, algorithm="HS256", headers=header) // CONNECT_SECRET is the security key provided by Amazon Connect
   ```

   在有效载荷中，您必须创建一个字符串键 `attributes`（按原样，全部为小写），并以一个对象作为其值。该对象必须有 string-to-string键值对。如果在任何一个属性中传递了字符串以外的任何内容，聊天将无法启动。

   联系人属性必须遵守 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes)API 设置的限制：
   + 密钥的长度下限必须为 1
   + 值的长度下限可以为 0

或者，您也可以在负载中将 segmentAttributes 字符串添加到[SegmentAttributeValue](https://docs.aws.amazon.com/connect/latest/APIReference/API_SegmentAttributeValue.html)对象映射中。这些属性是标准 Amazon Connect 属性。可以在流中访问它们。联系人属性必须遵守 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-SegmentAttributes)API 设置的限制。

## 替代方法：直接从代码片段中传递联系属性
<a name="pass-attributes-directly"></a>

**注意**  
此代码片段会将 `HostedWidget-` 添加到所有传递的联系属性键之前。在以下示例中，座席将看到键值对 `HostedWidget-foo: 'bar'`。
虽然这些属性的作用域使用 `HostedWidget-` 前缀，但它们在客户端仍是可变的。如果您的流中需要处理 PII 或不可变数据，请使用 JWT 设置。

以下示例介绍了如何在不启用小部件安全性的情况下直接从代码片段中传递联系属性。

```
<script type="text/javascript">
  (function(w, d, x, id){ /* ... */ })(window, document, 'amazon_connect', 'widgetId');
  amazon_connect('snippetId', 'snippetId');
  amazon_connect('styles', /* ... */);
  // ...

  amazon_connect('contactAttributes', {
   foo: 'bar'
  })
<script/>
```

### 在流中使用属性
<a name="contact-flow-usage-chat"></a>

[检查联系属性](check-contact-attributes.md)流数据块使用**用户定义**的命名空间来访问这些属性，如下图所示。您可以使用流数据块添加分支逻辑。完整路径是 `$.Attributes.HostedWidget-attributeName`。

![\[此图显示了流数据块分支到“有效”和“无效”提示。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/flow-check-contact-attrib.png)


## 您需要了解的内容
<a name="contact-attributes-chatwidget-important-notes"></a>
+ 通信小部件对整个编码令牌长度的限制为 6144 个字节。由于 JavaScript 使用 UTF-16 编码，因此每个字符使用 2 个字节，因此最大大小`encoded_token`应为 3000 个字符左右。
+ 应将 encoded\$1token 传递给 `callback(data)`。`authenticate` 片段不需要任何其他更改。例如：

  ```
  amazon_connect('authenticate', function(callback) {
    window.fetch('/token').then(res => {
      res.json().then(data => {
        callback(data.data);
      });
    });
  });
  ```
+ 使用 JWT 传递联系属性可确保数据的完整性。如果您能保护共享密钥并遵循适当的安全措施，就可以帮助确保数据不被不法分子篡改。
+ 联系属性仅在 JWT 中编码，未加密，因此可以解码并读取属性。
+ 如果您想使用[模拟聊天体验](chat-testing.md#test-chat)来测试聊天体验并包含联系属性，请务必用引号将键和值都括起来，如下图所示。  
![\[“测试设置”页面，引号中的联系属性键，引号中的值。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/test-chat-contact-attributes.png)

# 针对您的 Amazon Connect 聊天小部件的额外自定义
<a name="pass-customization-object"></a>

您可在聊天用户界面中添加以下可选自定义设置：
+ 在标题下拉菜单中而不是页脚中显示**结束聊天**按钮。
+ 屏蔽或隐藏显示名称。
+ “添加消息”图标。
+ 覆盖事件消息。
+ 配置一个确认对话框，当客户选择**结束聊天**按钮时，该对话框将呈现给客户。该对话框验证客户是否确实打算结束聊天会话。您可以自定义确认对话框、标题、消息和按钮文本。
+ 覆盖拒绝附件消息。

## 配置自定义设置对象
<a name="configure-customization-object"></a>

此示例演示如何实现一些可选的自定义设置。有关所有可能的自定义功能的列表，请参阅 [支持的选项和限制](#customization-options-constraints)。由于这些自定义功能是可选的，因此您可以实现以下示例中显示的部分或全部字段。根据需要替换 `eventNames.customer`、`eventNames.agent`、`eventNames.supervisor`、`eventMessages.participantJoined`、`eventMessages.participantDisconnect`、`eventMessages.participantLeft`、`eventMessages.participantIdle`、`eventMessages.participantReturned` 和 `eventMessages.chatEnded` 字符串。图标必须公开托管 URLs。

```
amazon_connect('customizationObject', {
        header: { 
            dropdown: true, 
            dynamicHeader: true,
        },
        transcript: { 
            hideDisplayNames: false, 
            eventNames: {
                customer: "User",
                agent: "Webchat Agent",
                supervisor: "Webchat Supervisor"
            },
            eventMessages: {
                participantJoined: "{name} has joined the chat",
                participantDisconnect: "",
                participantLeft: "{name} has dropped",
                participantIdle: "{name}, are you still there?",
                participantReturned: "",
                chatEnded: "Chat ended",
            },
            displayIcons: true,
            iconSources: { 
                botMessage: "imageURL",
                systemMessage: "imageURL",
                agentMessage: "imageURL",
                customerMessage: "imageURL",
            },
        },
        composer: {
            disableEmojiPicker: true,
            disableCustomerAttachments: true,
            alwaysHideToolbar: true,
            hide: false,
        },
        footer: {
            disabled:true,
            skipCloseChatButton: true,
        },
        endChat: {
            enableConfirmationDialog: true,
            confirmationDialogText: {
                title: "End Chat",
                message: "Are you sure you want to end this chat?",
                confirmButtonText: "End Chat",
                cancelButtonText: "Cancel",
        },
    },
    attachment: {
         // Default rejectedErrorMessage: Attachment was rejected.
        rejectedErrorMessage: "Custom Error Message: Files cannot exceed 15 MB." //this is customizable attribute 
    }
});
```

下图显示了使用示例时自定义设置的外观：

![\[示图显示可自定义的显示名称、菜单位置、图标以及“结束聊天”确认对话框。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-customization-diagram2.png)


## 支持的选项和限制
<a name="customization-options-constraints"></a>

下表列出了支持的自定义设置字段和推荐的值限制。


| 自定义布局选项 | Type | 描述 | 
| --- | --- | --- | 
|  `header.dropdown`  |  布尔值  |  呈现标题下拉列表而不是默认页脚  将此选项设置为 `true` 时，将显示**脚本下载**按钮并保持可见状态，直到您将该选项设置为 `false` 或删除该选项。   | 
| `header.dynamicHeader` | 布尔值 | 将标题动态设置为 “与 Bot/ 聊天AgentName”。 | 
| `header.hideTranscriptDownloadButton` | 布尔值 | 隐藏标题下拉菜单中的[下载文字记录](chat-widget-download-transcript.md)按钮。默认值为 false。 | 
|  `transcript.hideDisplayNames`  |  布尔值  |  隐藏所有显示名称，如果未提供 `eventNames`，将应用默认名称掩码。  | 
|  `transcript.eventNames.customer`  |  字符串  |  屏蔽客户的显示名称。  | 
|  `transcript.eventNames.agent`  |  字符串  |  屏蔽座席的显示名称。  | 
|  `transcript.eventNames.supervisor`  |  字符串  |  屏蔽主管的显示名称。  | 
|  ` transcript.eventMessages.participantJoined`  |  字符串  |  当有参与者加入聊天时，覆盖转录中的事件消息。如果指定空字符串，则转录中将省略事件消息。可以在消息中传递 `{name}`，并将被替换为相应参与者的显示名称。默认消息是 `{name} has joined the chat`。  | 
|  `transcript.eventMessages.participantDisconnect`  |  字符串  |  当有参与者从聊天中断开连接时，覆盖转录中的事件消息。如果指定空字符串，则转录中将省略事件消息。可以在消息中传递 `{name}`，并将被替换为相应参与者的显示名称。默认消息是 \$1`name} has been idle too long, disconnecting`。  | 
|  `transcript.eventMessages.participantLeft`  |  字符串  |  当有参与者离开聊天时，覆盖转录中的事件消息。如果指定空字符串，则转录中将省略事件消息。可以在消息中传递 `{name}`，并将被替换为相应参与者的显示名称。默认消息是 `{name} has left the chat`。  | 
|  `transcript.eventMessages.participantIdle`  |  字符串  |  当有参与者处于空闲状态时，覆盖转录中的事件消息。如果指定空字符串，则转录中将省略事件消息。可以在消息中传递 `{name}`，并将被替换为相应参与者的显示名称。默认消息是 `{name} has become idle`。  | 
|  `transcript.eventMessages.participantReturned`  |  字符串  |  当有参与者返回聊天时，覆盖转录中的事件消息。如果指定空字符串，则转录中将省略事件消息。可以在消息中传递 `{name} `，并将被替换为相应参与者的显示名称。默认消息是 `{name} has returned`。  | 
|  `transcript.eventMessages.chatEnded`  |  字符串  |  当聊天结束时，覆盖转录中的事件消息。如果指定空字符串，则转录中将省略事件消息。可以在消息中传递 `{name}`，并将被替换为相应参与者的显示名称。默认消息是 `Chat has ended!`  | 
|  `transcript.displayIcons`  |  布尔值  |  启用消息显示图标。  | 
|  `transcript.iconSources.botMessage`  |  字符串  |  为机器人消息显示的图标，必须托管在公共 URL 上。  | 
|  `transcript.iconSources.systemMessage`  |  字符串  |  为系统消息显示的图标，必须托管在公共 URL 上。  | 
|  `transcript.iconSources.agentMessage`  |  字符串  |  为座席消息显示的图标，必须托管在公共 URL 上。  | 
|  `transcript.iconSources.customerMessage`  |  字符串  |  为客户消息显示的图标，必须托管在公共 URL 上。  | 
|  `composer.alwaysHideToolbar`  |  布尔值  |  隐藏格式工具栏，该工具栏包含文本样式功能，例如粗体、斜体以及项目符号列表和编号列表选项。  | 
|  `composer.disableEmojiPicker`  |  布尔值  |  使用[富文本编辑器](enable-text-formatting-chat.md)时禁用表情符号选择器。  | 
| `composer.disableCustomerAttachments` | 布尔值 | 防止客户发送或上传附件。 | 
| `composer.hide` | 布尔值 | 隐藏作曲家 (`true`) 或显示它 (`false`)。要根据事件（例如代理加入时）切换作曲器，请`registerCallback`与`hideComposer`方法一起使用。有关更多信息，请参阅 [Amazon Connect 中支持可自定义的小部件片段字段](supported-snippet-fields.md)。<pre>document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatInterface.hideComposer(false)</pre> | 
|  `footer.disabled`  |  布尔值  |  隐藏默认页脚和**结束聊天**按钮。  | 
|  `footer.skipCloseChatButton`  |  布尔值  |  单击**结束聊天**按钮时直接关闭小部件，而不是显示**关闭**按钮。  | 
| `endChat.enableConfirmationDialog` | 布尔值 | 启用“结束聊天”确认对话框。如果未提供 confirmationDialogText，则使用默认文本。 | 
| `endChat.confirmationDialogText.title` | 字符串 | 覆盖“结束聊天”确认对话框的标题。 | 
| `endChat.confirmationDialogText.message` | 字符串 | 覆盖“结束聊天”确认对话框的消息。 | 
| `endChat.confirmationDialogText.confirmButtonText` | 字符串 | 覆盖“结束聊天”确认对话框中的“确认”按钮文本。 | 
| `endChat.confirmationDialogText.cancelButtonText` | 字符串 | 覆盖“结束聊天”确认对话框中的“取消”按钮文本。 | 
| `attachment.rejectedErrorMessage` | 字符串 | 覆盖聊天小部件附件被拒绝的错误消息。 | 

# 为在 Amazon Connect 中的聊天小部件下载文字记录
<a name="chat-widget-download-transcript"></a>

您可以在聊天窗口小部件中下载 PDF 格式的文字记录。

**Topics**
+ [启用标题下拉菜单](#chat-widget-download-transcript-enable-header-dropdown)
+ [下载 PDF 版聊天文字记录](#chat-widget-download-transcript-pdf)

## 启用标题下拉菜单
<a name="chat-widget-download-transcript-enable-header-dropdown"></a>

下载文字记录的按钮位于标题的下拉菜单中。要启用标题的下拉菜单，我们必须在小部件脚本中配置聊天小部件的 [customizationObject](pass-customization-object.md)。

```
amazon_connect('customizationObject', {
        header: { 
            dropdown: true, 
        }
});
```

请注意，启用下拉菜单将自动禁用页脚，因为**结束聊天**功能已移至页标题下拉菜单。如果您想保留页脚，则可以使用以下方法重新启用：

```
amazon_connect('customizationObject', {
        header: { 
            dropdown: true, 
        },
        footer: {
            disabled: false,
        }
});
```

## 下载 PDF 版聊天文字记录
<a name="chat-widget-download-transcript-pdf"></a>

启用标题下拉菜单后，您应该可以在聊天窗口小部件的左上角看到一个三点式菜单。在此下拉菜单中，您应该可以看到一个下载**聊天文字记录**按钮。

![\[显示下载聊天文字记录的按钮。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-widget-download-transcript-pdf-1.png)


选择下载**聊天记录**将开始下载 PDF。聊天记录 PDF 将显示所有消息、显示名称、时间戳和消息事件，例如参与者离开或加入。

![\[下载聊天记录示例。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-widget-download-transcript-pdf-2.png)


# 使用 Amazon Connect 开源示例自定义聊天内容
<a name="download-chat-example"></a>

您可以进一步自定义客户与座席互动时的聊天体验。在上使用 [Amazon Connect 开源库](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/cloudformationTemplates/asyncCustomerChatUX) GitHub。这是一个帮助您快速入门的平台。下面将介绍操作方式：
+  GitHub 存储库链接到一个 CloudFormation 模板，该模板启动启动 Lambda 函数的 Amazon API Gateway 终端节点。您能够以本模板为例。
+ 创建 AWS CloudFormation 堆栈后，您可以从您的应用程序调用此 API，导入预先构建的通信小部件，将响应传递给微件，然后开始聊天。

有关自定义聊天体验的更多信息，请参阅：
+ [Amazon Connect 服务 API 文档](https://docs.aws.amazon.com/connect/latest/APIReference/welcome.html)，尤其是 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API。
+  [Amazon Connect 参与者服务 API](https://docs.aws.amazon.com/connect-participant/latest/APIReference/Welcome.html)。
+  [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams)。用于将现有应用与 Amazon Connect 集成。您可以将联系人控制面板 (CCP) 组件嵌入到应用中。
+ [Amazon Connect 聊天 SDK 和示例实施](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/) 

# 使用 Amazon Connect 在您的应用程序中开始聊天 APIs
<a name="integrate-with-startchatcontact-api"></a>

使用 Amazon Connect APIs 中的 StartChatContact API 在您自己的应用程序中开始聊天。

要开始聊天，请使用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API。

当您首次探索聊天体验时，您会注意到聊天不计入历史指标报告中的**呼入的联系人**指标中。这是因为联系记录中聊天的启动方式是 **API**。

下图的联系记录显示了设置为 *API* 的*启动方式*。

![\[联系记录，启动方式设置为 API。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/ctr-api.png)


聊天转接到座席后，**呼入的联系人**指标会递增。转接的联系记录不再递增 API，但它会递增**呼入的联系人**。

# 聊天消息到达时向客户发送浏览器通知
<a name="browser-notifications-chat"></a>

通信小部件支持通过桌面设备向客户发送浏览器通知。具体而言，当您的客户收到新消息时，将通过其网络浏览器收到通知，而包含聊天窗口的网页不会有活动。当您的客户单击或轻触此通知时，他们会自动重定向到包含聊天窗口的网页。您的客户可以在每次聊天对话开始时启用或禁用通知。

下图显示了客户不在包含聊天窗口的网页上时收到的通知横幅示例。横幅告诉您的客户他们有新消息，并显示网站的名称。

![\[谷歌浏览器的横幅，上面写着您收到了一条新消息。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-notification-banner.png)


当通信小部件最小化时，客户还会收到一个通知图标，一个红点。下图显示了客户在聊天窗口最小化时收到的通知图标。

![\[通知图标。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-browser-notification.png)


这两个功能都自动包含在通信小部件中。您无需执行任何步骤即可将其提供给客户。

当您的客户发起聊天但尚未允许来自您的网站或域名的 allow/deny 通知时，他们会收到弹出式通知。在他们授予通知权限后，当他们不在带有聊天窗口的网页上时，就可以开始接收座席发送的任何消息或附件的浏览器通知了。即使您已经安装了通信小部件，该行为也依然适用。

## 如何测试
<a name="test-browser-notifications-chat"></a>

1. 在您以测试客户身份允许通知且座席已连接到聊天后，请最小化聊天窗口，然后打开一个新的浏览器实例，这样您就不在包含聊天窗口的网页上了。

1. 从座席窗口发送消息。

1. 作为测试客户，您将看到通知横幅。

1. 选择或轻触通知横幅。您将自动转到包含聊天窗口的网页。

1. 由于您之前最小化了聊天窗口，因此您还会在通信小部件上看到一个通知图标，一个红点。

如果您看不到浏览器通知，请检查以下内容：
+ 您正在使用[支持的浏览器](add-chat-to-website.md#chat-widget-supported-browsers)。
+ 带有聊天窗口 allowed/enabled 的网页的通知权限位于您的浏览器上。
+ 当你访问的网页不同于包含聊天窗口的网页 message/attachment 时，代理（或来自代理聊天会话的你）发送了一个新消息。要使小部件上的通知图标（红点）可见，请最小化聊天窗口。
+ 来自浏览器的通知没有休眠（暂时关闭）。

# 以编程方式断开 Amazon Connect 通信小部件的聊天会话
<a name="programmatic-chat-disconnect"></a>

您可以通过调用存储在通信控件中的`disconnect`方法，使用 “” JavaScript 以编程方式断开通信小组件的`iframe`聊天会话。从小部件的主文档，您可以使用以下代码片段来引用 `disconnect` 函数：

```
document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect()
```

您可以很容易地将其添加到现有的小部件脚本中。以下是一个代码片段示例：

```
<script type="text/javascript">
  (function(w, d, x, id){
    s=d.createElement('script');
    s.src='https://your-instance-alias.my.connect.aws/connectwidget/static/amazon-connect-chat-interface-client.js';
    s.async=1;
    s.id=id;
    d.getElementsByTagName('head')[0].appendChild(s);
    w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
  })(window, document, 'amazon_connect', '...');
  amazon_connect('styles', { iconType: 'CHAT', openChat: { color: '#ffffff', backgroundColor: '#123456' }, closeChat: { color: '#ffffff', backgroundColor: '#123456'} });
  amazon_connect('snippetId', '...');
  amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown', 'application/vnd.amazonaws.connect.message.interactive', 'application/vnd.amazonaws.connect.message.interactive.response' ]);
 
  // Add disconnect event listener
  window.addEventListener("pagehide", () => {
      document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
  });
</script>
```

## 实施和使用案例
<a name="implementation-chat-disconnect"></a>

通过编程方式调用断开连接功能在多种情况下都非常有用。它提供了在手动单击 `End Chat` 按钮之外何时终止对话的更多控制权。以下是一些何时调用 `disconnect` 的常见使用案例。

### 关闭或导航时
<a name="close-chat-disconnect"></a>

一个常见的使用案例是，将断开连接功能附加到浏览器或选项卡上下文被销毁时触发的事件上。`pagehide` 和 `beforeunload` 是在浏览器关闭时触发的常见事件。当用户刷新页面、导航到不同 URL 或者关闭选项卡或浏览器时，会触发这些事件。尽管在浏览器上下文被销毁时这两个事件都会被触发，但并不能保证 `disconnect` 函数能在浏览器的资源被清理完毕之前完全执行。

`pagehide` 是一个更现代的页面生命周期事件，受到所有主流浏览器和操作系统的支持。如果 `pagehide` 事件无法稳定地调用断开连接功能，可以尝试使用 `beforeunload` 作为替代事件。`beforeunload` 在 `pagehide` 之前触发，这可能为防止 `disconnect` 函数在浏览器关闭之前未能完成执行提供了额外的可靠性。`beforeunload` 存在可靠性问题，尤其是在 iOS 设备上。

以下是一个代码片段示例：

```
// Call disconnect when `beforeunload` triggers
window.addEventListener("beforeunload", (event) => {
    document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
});

// Call disconnect when `pagehide` triggers
window.addEventListener("pagehide", (event) => {
    document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
});
```

### 上下文切换时
<a name="context-chat-disconnect"></a>

另一个用例是在用户切换上下文时触发断开连接，例如当用户切换或最小化屏幕 tab/app 或锁定屏幕时。`visibilitychange` 事件可以可靠地处理上下文不再可见的这些场景。

以下是一个代码片段示例：

```
window.addEventListener("visibilitychange", () => {
    if (document.visibilityState === "hidden") {
        document.getElementById("amazon-connect-chat-widget-iframe").contentWindow.connect.ChatSession.disconnect();
    } else if (document.visibilityState === "visible") {
        ...
    }
});
```

# 传递自定义属性以覆盖 Amazon Connect 中的通信小部件中的默认属性
<a name="pass-custom-styles"></a>

要进一步自定义聊天用户界面，您可以通过传递自己的值来覆盖默认属性。例如，您可以将小部件的宽度设置为 400 像素，将高度设置为 700 像素（相比之下，默认尺寸为 300 像素 x 540 像素）。您也可以使用自己喜欢的字体颜色和大小。

## 如何为通信小部件传递自定义样式
<a name="chat-widget-pass-custom-styles"></a>

要传递自定义样式，请使用以下示例代码块并将其嵌入到您的控件中。 Amazon Connect 自动检索自定义样式。以下示例中显示的所有字段均为可选字段。

```
amazon_connect('customStyles', {
 global: {
     frameWidth: '400px',
     frameHeight: '700px',
     textColor: '#fe3251',
     fontSize: '20px',
     footerHeight: '120px',
     typeface: "'AmazonEmber-Light', serif",
     customTypefaceStylesheetUrl: "https://ds6yc8t7pnx74.cloudfront.net/etc.clientlibs/developer-portal/clientlibs/main/css/resources/fonts/AmazonEmber_Lt.ttf",
     headerHeight: '120px',
 },
 header: {
     headerTextColor: '#541218',
     headerBackgroundColor: '#fe3',
 },
 transcript: {
     messageFontSize: '13px',
     messageTextColor: '#fe3',
     widgetBackgroundColor: '#964950',
     agentMessageTextColor: '#ef18d3',
     systemMessageTextColor: '#ef18d3',
     customerMessageTextColor: '#ef18d3',
     agentChatBubbleColor: '#111112',
     systemChatBubbleColor: '#111112',
     customerChatBubbleColor: '#0e80f2',
 },
 footer: {
     buttonFontSize: '20px',
     buttonTextColor: '#ef18d3',
     buttonBorderColor: '#964950',
     buttonBackgroundColor: '#964950',
     footerBackgroundColor: '#0e80f2',
     startCallButtonTextColor: '#541218',
     startChatButtonBorderColor: '#fe3',
     startCallButtonBackgroundColor: '#fe3',
 },
 logo: {
     logoMaxHeight: '61px',   
     logoMaxWidth: '99%',
 },
  composer: {
     fontSize: '20px', 
 },
  fullscreenMode: true // Enables fullscreen mode on the widget when a mobile screen size is detected in a web browser.
})
```

## 支持的样式和限制
<a name="chat-widget-supported-styles"></a>

下表列出了支持的自定义样式名称和推荐的值限制。有些样式同时存在于全局和组件级别。例如，`fontSize` 样式既存在于全局中，又存在于记录组件中。组件级别样式在聊天小部件上具有更高的优先级。


|  自定义样式名称  |  说明  |  推荐的限制  | 
| --- | --- | --- | 
|  `global.frameWidth`  |  整个小部件框架的宽度  |  最小值：300 像素 最大值：窗口宽度 建议根据窗口大小进行调整  | 
|  `global.frameHeight`  |  整个小部件框架的高度  |  最小值：480 像素 最大值：窗口高度 建议根据窗口大小进行调整  | 
|  `global.textColor`  |  所有文本的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `global.fontSize`  |  所有文本的字体大小  |  针对不同的用例，建议使用 12 到 20 像素  | 
|  `global.footerHeight`  |  小部件页脚的高度  |  最小值：50 像素 最大值：框架高度 建议根据框架大小进行调整  | 
|  `global.typeface`  |  小部件中使用的字体。  |  此列表中的任何字体：Arial、Times New Roman、Times、Courier New、Courier、Verdana、Georgia、Palatino、Garamond、Book man、Tacoma、Trebuches MS、Arial Black、Impact、Comic Sans MS。 您也可以添加自定义字体/字体系列，但需要托管字体文件并设置公共读取权限。例如，您可以查看 [Amazon 开发者库](https://developer.amazon.com/en-US/alexa/branding/echo-guidelines/identity-guidelines/typography)中有关使用 Amazon Ember 字体系列的文档。  | 
|  `global.customTypefaceStylesheetUrl`  |  自定义字体文件的托管位置具有公共读取权限。  |  链接到托管字体文件的公共 HTTP 位置。例如，L AmazonEmber ight 字体 CDN 的位置是 `https://ds6yc8t7pnx74.cloudfront.net/etc.clientlibs/developer-portal/clientlibs/main/css/resources/fonts/AmazonEmber_Lt.ttf`  | 
|  `header.headerTextColor`  |  标题消息的文本颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `header.headerBackgroundColor`  |  标题背景的文字颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `global.headerHeight`  |  小部件标题的高度  |  建议根据使用的是标题、图片徽标还是两者同时使用来作调整。  | 
|  `transcript.messageFontSize`  |  所有文本的字体大小  |  针对不同的用例，建议使用 12 到 20 像素  | 
|  `transcript.messageTextColor`  |  记录消息的文本颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.widgetBackgroundColor`  |  文字记录背景的文字颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.customerMessageTextColor`  |  客户消息的文本颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.agentMessageTextColor`  |  座席消息的文本颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.systemMessageTextColor`  |  系统消息的文本颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.agentChatBubbleColor`  |  座席消息气泡的背景颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.customerChatBubbleColor`  |  客户消息气泡的背景颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `transcript.systemChatBubbleColor`  |  系统消息气泡的背景颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.buttonFontSize`  |  操作按钮文本的字体大小  |  建议根据页脚高度进行调整  | 
|  `footer.buttonTextColor`  |  操作按钮文本的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.buttonBorderColor`  |  操作按钮边框的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.buttonBackgroundColor`  |  操作按钮背景的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.BackgroundColor`  |  页脚背景的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.startCallButtonTextColor`  |  开始通话按钮文字的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.startCallButtonBorderColor`  |  开始通话按钮边框的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `footer.startCallButtonBackgroundColor`  |  开始通话按钮背景的颜色  |  任何 CSS 合法颜色值。有关更多信息，请参阅 [CSS 合法颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。  | 
|  `logo.logoMaxHeight`  |  徽标的最大高度  |  最小值：0 像素 最大值：标题高度 建议根据图像尺寸和框架高度进行调整  | 
|  `logo.logoMaxWidth`  |  徽标的最大宽度  |  最小值：0 像素 最大值：标题宽度 建议根据图像尺寸和框架宽度进行调整  | 
|  `composer.fontSize`  |  编辑器文本的字体大小  |  针对不同的用例，建议使用 12 到 20 像素  | 
|  `fullscreenMode`  |  在 Web 浏览器中检测到移动屏幕尺寸时，在小部件上启用全屏模式。  |  类型：布尔值  | 

以下是构成通信小部件的元素。

![\[构成通信小部件的元素。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-elements.png)


## 如何传递通信小部件的覆盖系统和机器人显示的名称和徽标
<a name="pass-override-system"></a>

要覆盖 Amazon Connect 管理员网站中设置的 System/Bot 显示名称和徽标配置，请将以下代码块嵌入到您的控件代码片段中。以下示例中显示的所有字段均为可选字段。

```
amazon_connect('customDisplayNames', {
 header: {
     headerMessage: "Welcome!",
     logoUrl: "https://example.com/abc.png",
     logoAltText: "Amazon Logo Banner"
 },
 transcript: {
     systemMessageDisplayName: "Amazon System",
     botMessageDisplayName: "Alexa"
 },
 footer: {
     textInputPlaceholder: "Type Here!",     
      endChatButtonText: "End Session",      
      closeChatButtonText: "Close Chat",      
      startCallButtonText: "Start Call"
 },
})
```

### 支持的属性和限制
<a name="supported-properties-displaynames"></a>


| 自定义样式名称 | 说明 | 推荐的限制 | 
| --- | --- | --- | 
|  `header.headerMessage`  | 标题消息的文字 | 最小长度是 1 个字符 长度上限：11 个字符  建议根据标题宽度进行调整 | 
|  `header.logoUrl`  | 指向徽标图像的网址 |  长度上限：2048 个字符 必须是指向 .png、.jpg 或 .svg 文件的有效网址 | 
|  `header.logoAltText`  | 用于覆盖徽标横幅 alt 属性的文本 |  长度上限：2048 个字符 | 
|  `transcript.systemMessageDisplayName`  | 覆盖 SYSTEM\$1MESSAGE 显示名称的文字 | 最小长度是 1 个字符 长度上限：26 个字符  | 
|  `transcript.botMessageDisplayName`  | 覆盖 BOT 显示名称的文字 | 最小长度是 1 个字符 长度上限：26 个字符  | 
|  `footer.textInputPlaceholder`  | 在文本输入中覆盖占位符的文字 | 最小长度是 1 个字符 最大长度：256 个字符  | 
|  `footer.endChatButtonText`  | 覆盖聊天结束按钮文本的文字 | 最小长度是 1 个字符 最大长度：256 个字符 建议根据按钮宽度进行调整  | 
|  `footer.closeChatButtonText`  | 覆盖聊天关闭按钮文本的文字 | 最小长度是 1 个字符 最大长度：256 个字符 建议根据按钮宽度进行调整  | 
|  `footer.startCallButtonText`  | 覆盖开始通话按钮文本的文字 | 最小长度是 1 个字符 最大长度：256 个字符 建议根据按钮宽度进行调整  | 

## 预览使用了自定义属性的通信小部件
<a name="chat-widget-preview"></a>

在将其投入生产之前，请务必先预览使用了自定义属性的通信小部件。如果设置不当，自定义值可能会破坏通信小部件的用户界面。建议您在将其发布给客户之前，在不同的浏览器和设备上进行测试。

以下是使用不正确值时可能出现故障的几个示例，以及建议的修复方法。
+ **问题：**小部件窗口占用了太多屏幕空间。

  **修复方法：**使用较小的 `frameWidth` 和 `frameHeight`。
+ **问题：**字体太小或太大。

  **修复方法：**调整字体大小。
+ **问题：**结束聊天（页脚）下方有一块空白区域。

  **修复方法：**使用较小的 `frameHeight` 或较大 `footerHeight`。
+ **问题：**结束聊天按钮太小或太大。

  **修复方法：**调整 `buttonFontSize`。
+ **问题：**结束聊天按钮位于页脚区域之外。

  **修复方法：**使用较大的 `footerHeight` 或较小 `buttonFontSize`。

# 使用 CSS/ 瞄准你的 Amazon Connect 小工具按钮和框架 JavaScript
<a name="target-widget-button"></a>

通信控件将控 open/close 件按钮和控件框架直接呈现在主机网站上。您可以使用特定的选择器来使用 CSS 定位这些元素或在中 JavaScript引用它们。

**提示**  
要更新小部件按钮的颜色或小部件本身的样式，请使用 [Amazon Connect 管理网站](add-chat-to-website.md#customize-chat-widget)。要实现更可定制的样式，您可以直接[传递自定义样式](pass-custom-styles.md)给通信小部件。

## 控件元素 IDs 和示例
<a name="widget-elementid"></a>

下图显示聊天小部件按钮在用户屏幕上的显示效果。第一个图显示“打开”按钮，用于打开聊天小部件。第二个图显示“关闭”按钮，用于关闭聊天小部件。

![\[Side-by-side 用于打开和关闭聊天窗口的聊天小部件的图像。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/widget-elements.png)


1.  “打开”小部件按钮：`#amazon-connect-open-widget-button`

1. “关闭”小部件按钮：`#amazon-connect-close-widget-button`

1. 小部件框架：`#amazon-connect-widget-frame`

   1. 打开时的小部件框架：`#amazon-connect-widget-frame.show`

   1. 关闭时的小部件框架：`#amazon-connect-widget-frame:not(.show)`

以下是修改这些元素的 CSS 样式表示例：

```
/* Target widget button while widget is minimized */
#amazon-connect-open-widget-button {
  ...
}

/* Target widget button while widget is showing */
#amazon-connect-close-widget-button {
  ...
}

/* Target widget frame */
#amazon-connect-widget-frame {
  ...
}

/* Target widget frame while it is showing */
#amazon-connect-widget-frame.show {
  ...
}

/* Target widget frame while it is minimized */
#amazon-connect-widget-frame:not(.show) {
  ...
}
```

以下是使用 JavaScript以下方法引用这些元素的示例：

```
const openWidgetButton = document.getElementById("amazon-connect-open-widget-button");
const closeWidgetButton = document.getElementById("amazon-connect-close-widget-button");

const widgetFrame = document.querySelector("#amazon-connect-widget-frame");
const openWidgetFrame = document.querySelector("#amazon-connect-widget-frame.show");
const hiddenWidgetFrame = document.querySelector("#amazon-connect-widget-frame:not(.show)");
```

# 排查您的 Amazon Connect 通信小部件问题
<a name="ts-cw"></a>

本主题适用于需要调查在 Amazon Connect 管理网站中配置通信控件时可能出现的问题的开发人员。

**Topics**
+ [“出问题了”](#sww)
+ [客户未收到代理消息：网络或 WebSocket 已断开连接](#mam)
+ [打开第三方链接时绕过 CORS](#bcwotpl)

## “出问题了”
<a name="sww"></a>

如果您在加载通信小部件时看到以下**错误**消息，请打开浏览器工具查看错误日志。

![\[错误消息显示“出错了”。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-error-message.png)


以下是可能导致此错误的常见问题：

### 400 请求无效
<a name="400-invalid-request"></a>

如果日志显示 400 请求无效，可能有以下几种原因：
+ 您的通信小部件未在允许的域上运行。您必须明确指定托管小部件的域。
+ 向端点发出的请求格式不正确。这通常只有在嵌入式片段的内容被修改时才会出现这种情况。

### 401 未经授权
<a name="401-unauthorized"></a>

![\[“出错了”错误信息。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/something-went-wrong.png)


如果日志显示 401 未经授权，说明是 JSON Web 令牌 (JWT) 身份验证存在问题。它显示上面的错误页面。

获得 JWT 后，您需要在 `authenticate` 回调函数中实施它。以下示例显示了如何在获取令牌后使用它：

```
amazon_connect('authenticate', function(callback) {
  window.fetch('/token').then(res => {
    res.json().then(data => {
      callback(data.data);
    });
  });
});
```

以下是需要实施的更基本的版本：

```
amazon_connect('authenticate', function(callback) {
   callback(token);
});
```

有关实施 JWT 的说明，请参阅 [第 3 步：确认并复制通信小部件代码和安全密钥](add-chat-to-website.md#confirm-and-copy-chat-widget-script)。

如果您已经实施了回调，以下情况仍可能导致 401：
+ 签名无效
+ 令牌已过期

### 404 未找到
<a name="404-not-found"></a>

出现 404 状态码通常是因为请求的资源不存在：
+ API 请求中指定的 widgetId 无效
+ widgetId 有效，但关联的流已被删除或存档
+ 该小部件尚未发布或已被删除

确认您的代码片段与从 Amazon Connect 管理员网站复制的内容完全相同，并且所有标识符均未更改。

如果标识符未更改，而您看到的是 404，请联系 AWS 支持。

### 500 内部服务器错误
<a name="500-internalservererror-chatwidget"></a>

这可能是由于您的服务相关角色没有启用聊天所需的权限所致。如果您的 Amazon Connect 实例是在 2018 年 10 月之前创建的，就会出现这种情况，因为您尚未设置服务相关角色。

**解决方案**：为与 Amazon Connect 实例关联的角色上添加 `connect:*` 策略。有关更多信息，请参阅 [使用 Amazon Connect 的服务相关角色和角色权限](connect-slr.md)。

如果您的服务相关角色拥有适当的权限，请联系 AWS 支持。

## 客户未收到代理消息：网络或 WebSocket 已断开连接
<a name="mam"></a>

在聊天会话期间，使用聊天应用程序的客户会失去 network/WebSocket 连接。他们很快就会重新获得连接，但在此期间座席发送的消息不会显示在客户的聊天界面上。

下图显示了客户的聊天界面和客服联系人控制面板的示例 side-by-side。座席发送的消息不会显示在客户的聊天会话中。但是，在座席看来，客户似乎已经收到了。

![\[CCP 中未发送给联系人的消息。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/tw-cw-001-message-not-sent.png)


如果客户的聊天应用程序失去 network/WebSocket 连接，聊天用户界面必须执行以下操作才能检索 future 消息以及断开连接时发送给它的消息：
+ 重新建立 WebSocket 连接，以便再次接收 future 传入的消息。
+ 发送 [chatSession.getTranscript](https://github.com/amazon-connect/amazon-connect-chatjs?tab=readme-ov-file#chatsessiongettranscript) ([getTranscripts](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) API) 请求，检索客户断开连接时发送的所有缺失消息。

如果座席在客户的聊天用户界面断开连接时发送消息，则消息会成功存储在 Amazon Connect 后端：CCP 按预期运行，消息全部记录在记录中，但客户的设备无法接收消息。当客户端重新连接到时 WebSocket，消息中会出现间隔。将来的传入消息将再次从中出现 WebSocket，但除非代码明确调用 [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html)API，否则仍会缺少间隙消息。

### 解决方案
<a name="solution-network-disconnected"></a>

使用 [ChatSession。 onConnectionEstablished](https://github.com/amazon-connect/amazon-connect-chatjs?tab=readme-ov-file#chatsessiononconnectionestablished)用于调用 [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html)API 的事件处理程序。 WebSocket 重新连接时会触发`chatSession.onConnectionEstablished`事件处理程序。ChatJS 具有内置的连接心跳和重试逻辑。 WebSocket 但是，由于 ChatJS 不会存储记录，您必须在聊天用户界面上添加自定义代码，才能再次手动获取副本。

以下代码示例展示了如何实现 `onConnectionEstablished` 来调用 `GetTranscript`。

```
import "amazon-connect-chatjs";

const chatSession = connect.ChatSession.create({
  chatDetails: {
    ContactId: "the ID of the contact",
    ParticipantId: "the ID of the chat participant",
    ParticipantToken: "the participant token",
  },
  type: "CUSTOMER",
  options: { region: "us-west-2" },
});

// Triggered when the websocket reconnects
chatSession.onConnectionEstablished(() => {
  chatSession.getTranscript({
    scanDirection: "BACKWARD",
    sortOrder: "ASCENDING",
    maxResults: 15,
    // nextToken?: nextToken - OPTIONAL, for pagination
  })
    .then((response) => {
      const { initialContactId, nextToken, transcript } = response.data;
      // ...
    })
    .catch(() => {})
});
```

```
function loadLatestTranscript(args) {
    // Documentation: https://github.com/amazon-connect/amazon-connect-chatjs?tab=readme-ov-file#chatsessiongettranscript
    return chatSession.getTranscript({
        scanDirection: "BACKWARD",
        sortOrder: "ASCENDING",
        maxResults: 15,
        // nextToken?: nextToken - OPTIONAL, for pagination
      })
      .then((response) => {
        const { initialContactId, nextToken, transcript } = response.data;
        
        const exampleMessageObj = transcript[0];
        const {
          DisplayName,
          ParticipantId,
          ParticipantRole, // CUSTOMER, AGENT, SUPERVISOR, SYSTEM
          Content,
          ContentType,
          Id,
          Type,
          AbsoluteTime, // sentTime = new Date(item.AbsoluteTime).getTime() / 1000
          MessageMetadata, // { Receipts: [{ RecipientParticipantId: "asdf" }] }
          Attachments,
          RelatedContactid,
        } = exampleMessageObj;

        return transcript // TODO - store the new transcript somewhere
      })
      .catch((err) => {
        console.log("CustomerUI", "ChatSession", "transcript fetch error: ", err);
      });
}
```

有关另一个示例，请参阅[上的这个开源实现 GitHub](https://github.com/amazon-connect/amazon-connect-chat-interface/blob/c88f854073fe6dd45546585c3bfa363d3659d73f/src/components/Chat/ChatSession.js#L408)。

## 打开第三方链接时绕过 CORS
<a name="bcwotpl"></a>

为增强安全性，通信小部件在沙盒环境中运行。因此，无法打开小部件内共享的第三方链接。

**解决方案**

有两种方法可以绕过 CORS 来允许打开第三方链接。
+ **（推荐）**

  更新沙盒属性以允许在新选项卡中打开链接。这可以通过在代码片段中添加以下属性来完成：

  ```
  amazon_connect('updateSandboxAttributes', 'allow-scripts allow-same-origin allow-popups allow-downloads allow-top-navigation-by-user-activation allow-popups-to-escape-sandbox')
  ```
**注意**  
可以根据需要更新属性值以允许执行特定操作。这是如何允许在新选项卡中打开链接的示例。
+ 移除沙盒属性。这可以通过在代码片段中添加以下属性来实现：

  ```
  amazon_connect('removeSandboxAttribute', true)
  ```

# 添加联系前表单或聊天前表单
<a name="add-precontact-form"></a>

您可以在开始联系之前获取客户信息：
+ **联系前表单**：添加该表单可以在开始任务或电子邮件联系之前从客户那里获取信息。
+ **聊天前表单**：添加该表单可以在开始聊天联系之前从客户那里获取信息。

捕获信息后，您可以通过联系人控制面板（CCP）显示给座席，或者在流的其他地方使用这些信息。

要创建表单，您需要创建一个自定义视图并使用连接操作按钮组件。有关视图的更多信息，请参阅[使用 Amazon Connect 中的用户界面生成器获取 step-by-step指南中的资源](no-code-ui-builder.md)。

连接操作按钮允许您接收表单中的用户输入，并选择提交表单时要采取的操作——开始 task/email 或聊天。

# 启用聊天后调查
<a name="enable-post-chat-survey"></a>

聊天后调查使您能够在聊天对话结束后立即收集最终客户的反馈。使用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 中的**`DisconnectOnCustomerExit`**参数，您可以配置在最终客户断开连接时自动断开代理连接，从而确保无论哪个参与者先断开连接，都能始终如一地触发断开连接流程。

## 实施选项
<a name="post-chat-survey-implementation"></a>

有两种方法可以启用聊天后调查：

### 对于自定义聊天控件
<a name="post-chat-survey-custom-builder"></a>

如果你使用的是自定义聊天实现：

1. 升级到最新版本的[amazon-connect-chatjs](https://github.com/amazon-connect/amazon-connect-chatjs)。

1. 将`DisconnectOnCustomerExit`参数添加到您的 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 请求中：

   ```
   {
       "DisconnectOnCustomerExit": ["AGENT"],
       // ... other StartChatContact parameters
   }
   ```

### 适用于 Amazon Connect 通信小工具
<a name="post-chat-survey-communication-widget"></a>

如果您使用的是 Amazon Connect 通信小工具：

1. 打开 Amazon Connect 控制台并导航至**通信小工具**。

1. 通过 “通讯小工具” 页面启用聊天后调查设置。  
![\[显示聊天后调查选项的 “通讯控件” 设置页面。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/post-chat-survey-communication-widget.png)

## 更新联系流程，将聊天后调查添加为断开连接流程
<a name="post-chat-survey-disconnect-flow"></a>

要启用聊天后调查，您需要更新与聊天解决方案相关的断开连接流程。配置完成后，调查将在客户结束聊天会话时自动触发。

有关创建断开连接流程的信息，请参阅[聊天场景示例](web-and-mobile-chat.md#example-chat-scenario)。

有两种方法可以在断开连接流程中实施调查：
+ **选项 \$11: 使用 ShowView 区块**-[Amazon Connect 流数据块：显示视图](show-view-block.md) 使用显示自定义调查界面。
+ **选项 \$12: 使用 Lex**-与 Amazon Lex 集成以进行基于文本的调查收集。有关更多信息，请参阅 [将 Amazon Lex 自动程序添加到 Amazon Connect](amazon-lex.md)。

**注意**  
对于主管闯入场景，请确保在**转移到**队列之前添加一个[Amazon Connect 流数据块：设置工作队列](set-working-queue.md)方块。省略它会导致聊天联系人终止而不是转移此功能。  

![\[流程图显示了主管闯入场景的 “转移到队列” 之前的 “设置工作队列” 模块。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/post-chat-survey-set-working-queue-block.png)


**联系人追踪记录**  
当客户结束聊天会话时，Amazon Connect `disconnectReason` 将`CUSTOMER_DISCONNECT`设置为[ContactTraceRecord](ctr-data-model.md#ctr-ContactTraceRecord)。配置完成后`DisconnectOnCustomerExit`，系统会生成新的联系人 ID (`nextContactId`) 并启动已配置的断开连接流程。  
示例：  

```
{
    "contactId": "104c05e3-abscdfre",
    "nextContactId": "4cbae06d-ca5b-1234567",
    "channel": "CHAT",
    "initiationMethod": "DISCONNECT",
    "disconnectReason": "CUSTOMER_DISCONNECT"
}
```
[Amazon Connect 中的联系属性如何运作](what-is-a-contact-attribute.md)将在联系人搜索和联系人详细信息中更新。  

![\[显示聊天后调查的联系人属性的联系人详细信息。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/post-chat-survey-contact-attributes.png)


## 其他资源
<a name="post-chat-survey-additional-resources"></a>
+ [StartChatContact API](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)
+ [Amazon Connect 中的入站流示例，提供首次联系体验](sample-inbound-flow.md)
+ [聊天场景示例](web-and-mobile-chat.md#example-chat-scenario)
+ [Amazon Connect 流数据块：设置工作队列](set-working-queue.md)
+ [Amazon Connect 流数据块：转移到队列](transfer-to-queue.md)
+ [Amazon Connect ShowView](https://docs.aws.amazon.com/connect/latest/adminguide/show-view-block.html)
+ [Amazon Connect with Lex](https://docs.aws.amazon.com/connect/latest/adminguide/amazon-lex.html)
+ [Amazon Connect 中的联系属性如何运作](what-is-a-contact-attribute.md)

# 将 Amazon Connect 聊天集成到移动应用程序中
<a name="integrate-chat-with-mobile"></a>

本主题将介绍如何将 Amazon Connect 聊天功能集成到移动应用程序中。可以使用以下选项之一：
+ [WebView 整合](#webview)
+ [iOS 和安卓版Amazon Connect Chat SDKs ](#integrate-chat-with-mobile-sdks-for-mobile)
+ [React Native 集成](#react-native-integration)

使用 Amazon Connect [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 发起联系。

**Topics**
+ [使用哪个集成选项](#integrate-options)
+ [Amazon Connect 聊天集成工作流程](#integrate-chat-with-mobile-workflow)
+ [开始使用 Amazon Connect 聊天集成](#integrate-chat-with-mobile-getting-started)

## 使用哪个集成选项
<a name="integrate-options"></a>

本节描述了每个集成选项，以帮助您决定将哪个集成选项用于您的解决方案。

### WebView 整合
<a name="webview"></a>

Amazon Connect Chat WebView 集成允许您以最少的开发工作将完整的聊天体验嵌入到您的移动应用程序中。该方法在 Android 上使用 `WebView`，在 iOS 上使用 `WKWebView`，以提供无缝且全面的聊天界面。对于寻求一种无需大量自定义即可快速集成聊天功能的 out-of-the-box解决方案的团队来说，它是理想的选择。

这种方法可确保安全通信，并利用基于 Web 的 Amazon Connect 聊天界面。但是，您需要将应用程序配置为 JavaScript 正确处理 Cookie。

有关实现 WebView 集成的更多信息，请参阅 Amazon Connect 聊天[界面示例](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples) GitHub 存储库。

**建议**： WebView基于基础的集成非常适合快速开发和最少的维护，同时确保全面的聊天功能。

### Amazon Connect 手机版聊天 SDKs
<a name="integrate-chat-with-mobile-sdks-for-mobile"></a>

iOS 和 Android 版的 Chat 简化了原生移动应用程序的 Amazon Connect 聊天集成。 Amazon Connect SDKs 它 SDKs 可以帮助处理客户端聊天逻辑和后端通信，类似于 Amazon Connect ChatJS 库。

 Amazon Connect 聊天 SDKs 结束了Amazon Connect参与者服务， APIs并抽象了聊天会话的管理以及 WebSocket. 这使您可以专注于用户界面和体验，同时依靠 Amazon Connect Chat SDK 与所有后端服务进行交互。这种方法仍然需要您使用自己的聊天后端来调用 Amazon Connect `StartChatContact` API 来发起联系。
+ 有关基于 Swift 的 iOS 开发工具包的更多信息，请参阅适用于 iO [S GitHub 的Amazon Connect Chat SDK 页面](https://github.com/amazon-connect/amazon-connect-chat-ios)。
+ 有关基于 Kotlin 的 Android SDK 的更多信息，请参阅适用于 Android 的 [Amazon Connect Chat SDK 页面](https://github.com/amazon-connect/amazon-connect-chat-android) GitHub 。

**优点**：Native SDKs 支持强大的功能和高性能，非常适合需要深度自定义和无缝用户体验的应用程序。

### React Native 集成
<a name="react-native-integration"></a>

Amazon Connect Chat React Native 集成提供了一种跨平台解决方案。它使团队能够使用共享代码库为 Android 和 iOS 构建聊天功能。这种方法在利用 React Native 的创建强大移动应用程序的功能的同时，平衡了自定义和开发效率。

此集成使用原生桥接来访问高级功能，并确保跨平台的一致性能和统一的用户体验。通过使用诸如`react-native-websocket`和 API 调用之类的库来实现 WebSocket 通信等关键功能会更容易`axios`。

**最适合**：希望在保持功能灵活性的同时最大化代码重用的团队。

## Amazon Connect 聊天集成工作流程
<a name="integrate-chat-with-mobile-workflow"></a>

下图显示了使用移动应用程序的客户与座席之间的编程流。此图中的编号文字与图片下方的编号文本相对应。

![\[该图显示了 Amazon Connect 聊天程序流程。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/integrate-chat-mobile-diagram.png)


**在图中**

1. 当客户在移动应用程序中开始聊天时，应用程序应 Amazon Connect 使用该 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 向发送请求。这需要特定的参数（ IDs 例如 API 端点以及[实例](amazon-connect-instances.md)和[联系](connect-contact-flows.md)流程）来进行身份验证和启动聊天。

1. `StartChatContact` API 会与您的后端系统交互以获取作为聊天会话唯一标识符的参与者令牌和联系 ID。

1. 应用程序的用户界面会将 `StartChatContact` 响应传递给移动设备 SDK，以便 SDK 能够与 [Amazon Connect 参与者服务](https://docs.aws.amazon.com/connect/latest/APIReference/API_Operations_Amazon_Connect_Participant_Service.html)进行正确通信并设置客户的聊天会话。

1. SDK 将向用户界面公开 [chatSession](https://github.com/amazon-connect/amazon-connect-chat-ios?tab=readme-ov-file#chatsession-apis) 对象，其中包含与聊天会话交互的易用方法。

1. 在幕后，SDK 使用 [AWS SDK](https://docs.aws.amazon.com/connect/latest/APIReference/API_Operations_Amazon_Connect_Participant_Service.html) 与 [Amazon Connect 参与者服务](https://aws.amazon.com/developer/tools/)交互。与 Amazon Connect 参与者服务的沟通负责所有客户与聊天会话的互动。这包括诸如`CreateParticipantConnection`、`SendMessage`、`GetTranscript` 或 `DisconnectParticipant` 之类的操作。

1. SDK 还管理从代理接收消息、事件和附件所需的 WebSocket 连接。所有这些都将由 SDK 处理和解析，然后以易用的结构显示在用户界面上。

## 开始使用 Amazon Connect 聊天集成
<a name="integrate-chat-with-mobile-getting-started"></a>

以下步骤和资源将帮助您开始将 Amazon Connect Chat 集成到原生移动应用程序中：

1. 您可以通过查看上的 [startChatContactAPI](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/cloudformationTemplates/startChatContactAPI) 示例，快速设置[CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)堆栈以提供必要的后端进行 GitHub调用 StartChatContact 。

1. 有关展示如何构建由 Amazon Connect Chat 支持的移动聊天界面的示例 SDKs，请查看我们的[用户界面示例](https://github.com/amazon-connect/amazon-connect-chat-ui-examples) GitHub 项目。

   请参阅我们的 [iOS](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/iOSChatExample) 和 [Android](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/androidChatExample) 聊天示例，这些示例展示了如何使用适用于 iOS/Android 的 Amazon Connect 聊天 SDK 为聊天应用程序提供支持。

1. 查看适用于 [iOS 的Amazon Connect 聊天 SDK 和适用于](https://github.com/amazon-connect/amazon-connect-chat-ios) [Android 的Amazon Connect 聊天 SDK](https://github.com/amazon-connect/amazon-connect-chat-android) GitHub 页面。该 GitHub 页面包含 API 文档和实施指南，其中解释了所有先决条件和安装步骤。

1. 设置 React Native 集成：利用 [React Native](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/connectReactNativeChat) 示例获取有关实施基于 React Native 的解决方案的指导。

1. 如果您对在移动应用程序中设置或使用 Amazon Connect 聊天功能 SDK 有任何疑问或问题，可以在[适用于 iOS 的Amazon Connect 聊天功能 SDK 问题](https://github.com/amazon-connect/amazon-connect-chat-ios/issues)页面或[适用于 Android 的Amazon Connect 聊天功能 SDK 问题](https://github.com/amazon-connect/amazon-connect-chat-android/issues)页面提交问题。如果移动聊天用户界面示例存在问题，您可以在 [Amazon Connect 聊天用户界面示例问题](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/issues)页面提交问题。

# 为提升客户的聊天体验在 Amazon Connect 中启用文本格式化
<a name="enable-text-formatting-chat"></a>

借助 Amazon Connect 消息格式化，您可以让客户和座席快速为聊天消息添加结构和清晰度。

**Topics**
+ [支持的格式类型](#supported-format-types)
+ [启用消息格式化](#how-to-enable-message-formatting)
+ [如何添加电子邮件和电话链接](#add-email-phone-links)
+ [如何添加聊天机器人消息](#add-bot-messages)

## 支持的格式类型
<a name="supported-format-types"></a>

您可以使用 Markdown 在聊天用户界面和座席应用程序上提供以下类型的格式：
+ 粗体
+ 斜体
+ 项目符号列表
+ 编号列表
+ 超链接
+ 表情符号
+ 附件。要启用附件，请遵循 [在您的 CCP 中启用附件，以便客户和座席可以共享和上传文件](enable-attachments.md)。

## 如何启用消息格式化
<a name="how-to-enable-message-formatting"></a>

1. 创建新的[聊天用户界面](add-chat-to-website.md)时，富文本格式会立即启用。无需其他配置。

1. 要在现有的[聊天用户界面](add-chat-to-website.md)添加文本格式化功能，请使用以下以粗体突出显示的代码更新[通信小部件代码](add-chat-to-website.md)：

   ```
       (function(w, d, x, id){
           s=d.createElement('script');
           s.src='https://your-instance-alias.my.connect.aws/connectwidget/static/amazon-connect-chat-interface-client.js';
           s.async=1;
           s.id=id;
           d.getElementsByTagName('head')[0].appendChild(s);
           w[x] =  w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
       })(window, document, 'amazon_connect', 'widget-id');
       amazon_connect('styles', { openChat: { color: 'white', backgroundColor: '#123456'}, closeChat: { color: 'white', backgroundColor: '#123456'} });
       amazon_connect('snippetId', 'snippet-id');
       amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown' ]);
   ```

   当您从 Amazon Connect 控制台获取代码片段时，以红色突出显示的代码将设置为正确的值。您选择添加或删除的唯一内容是最后一行以粗体显示的 `supportedMessagingContentTypes`。

1. 要将文本格式化功能添加到您自己的自定义聊天用户界面（例如，[聊天界面](https://github.com/amazon-connect/amazon-connect-chat-interface)或 [ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs) 上自己的用户界面解决方案），请遵循以下步骤：

   1. 调用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API。调用 `StartChatContact` 时，添加 `SupportedMessagingContentTypes` 参数，如以下示例中的粗体所示：

      ```
      // Amazon Connect StartChatContact API
      {
          "Attributes": { 
              "string" : "string" 
          },
          "ClientToken": "string",
          "ContactFlowId": "your flow ID",
          "InitialMessage": { 
              "Content": "string",
              "ContentType": "string"
          },
          "InstanceId": "your instance ID",
          "ParticipantDetails": { 
              "DisplayName": "string"
          }
          
          // optional
         "SupportedMessagingContentTypes": [ "text/plain", "text/markdown" ]
      }
      ```

   1. 将 `chatjs` 作为对象导入，如以下示例所示：

      ```
      import "amazon-connect-chatjs";
      
      this.session = connect.ChatSession.create({
            ...
          });
      
      this.session.sendMessage({
            message: "message-in-markdown-format",
            contentType: "text/markdown"
      });
      ```

      如果您不使用 ChatJs，请参阅以下主题，了解有关通过 Amazon Connect 发送降价文本的信息 APIs：[StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)和[SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html)。

   1. 使用 Markdown 发送消息。有关如何发送消息的示例，请参阅前面将 `chatjs` 作为对象导入的代码片段。您可以使用简单的 Markdown 来格式化聊天中的文本。如果你[现在已经在使用 chatjs 发送纯文本消息，你可以修改现有的逻辑来](https://github.com/amazon-connect/amazon-connect-chatjs/blob/master/src/core/chatController.js#L66)调用 [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html)as，`contentType`而不是在你想要发送 markdown 消息`text/plain`时调用。`text/markdown`请务必更新 `sendMessage` 参数，使您的消息包含 Markdown 格式。有关更多信息，请参阅 [Markdown 指南基本语法](https://www.markdownguide.org/basic-syntax/)。

   1. 在 UI 软件包中执行您自己的逻辑，以便在输入区和聊天记录中呈现 Markdown 消息。如果您使用 React，可以使用 [react-markdown](https://github.com/remarkjs/react-markdown) 作为参考。

**注意**  
只有在聊天用户界面中为客户启用文本格式化功能后，您的座席才会看到该功能。如果客户的聊天用户界面不支持或未启用文本格式化，座席将无法使用文本格式撰写和发送消息。
除附件外，所有文本格式化功能均可用于[快速响应](create-quick-responses.md)。

## 如何添加电子邮件和电话链接
<a name="add-email-phone-links"></a>

以下示例显示了如何在您的网络和移动应用程序中添加可点击和可调用的链接。

```
Call us today: [+1 (123) 456-7890](tel:+11234567890)
[Call Us](tel:+11234567890)
[Skype Us](callto:+91123-456-7890)
[Fax Us](fax:+91123-456-7890)
[Text Us](SMS:+91123-456-7890)
[Email Us](mailto:name@email.com)
```

## 如何添加聊天机器人消息
<a name="add-bot-messages"></a>

启用聊天消息编辑器功能后，您可以对以下类型的聊天机器人消息使用富文本格式：
+ [播放提示](play.md)流
+ [获取客户输入](get-customer-input.md)流
+ `SYSTEM_MESSAGE`
+ `Lex BOT`
+ `Third Party BOT`
+ `Lex BOT Lambda`

下图显示了如何在[播放提示](play.md)流数据块中手动启用提示：

![\[流数据块图像和带有 2 个链接的提示，一个指向常见问题解答，另一个指向电话号码。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-rtf-play-prompt-flow-1.png)


下图显示了如何在[获取客户输入](get-customer-input.md)流数据块中手动启用提示，然后将流数据块与 Amazon Lex 机器人相关联：

![\[流数据块图像和带有 2 个链接的提示，一个指向常见问题解答，另一个指向电话号码。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-rtf-get-customer-flow.png)


下图显示了提示在 SYSTEM\$1MESSAGE 和各种 BOT 消息类型中的显示方式：

![\[图片显示了 SYSTEM 和 BOT 消息中的“查看我们的常见问题解答”和“联系我们”链接。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-rtf-sys-bot-messages.png)


下图显示了如何在 Amazon Lex 机器人意图中设置提示：

![\[Amazon Lex 意图的图片，其中包含一个带有 2 个链接的提示，一个指向常见问题解答，另一个指向电话号码。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-rtf-lex-flow.png)


有关意图的更多信息，请参阅*《Amazon Lex V2 开发人员指南》*中的[添加意图](https://docs.aws.amazon.com/lexv2/latest/dg/add-intents.html)。*有关 Lambda 消息的更多信息，请参阅 Amazon [Lex V2 开发者指南中的使用 AWS Lambda 函数启用自定义逻辑](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html)。*

# 启用 Amazon Connect 聊天客户的通知功能
<a name="message-receipts"></a>

您可以在[聊天用户界面](add-chat-to-website.md)启用消息*已送达*和*已读*，以便您的客户知道他们发送的消息的状态。这为客户提供了透明度，改善了整体聊天体验。

无论是否启用了消息回执，都将始终发送消息回执数据和事件，并且可以在网络日志中看到。在聊天用户界面中启用和禁用消息回执仅影响回执是否会显示在通信小部件的转录中。

**提示**  
默认情况下，[测试聊天](chat-testing.md#test-chat)体验、联系人控制面板 (CCP) 和聊天小组件的[可下载开源示例](download-chat-example.md)已启用消息回执。

**在聊天用户界面启用消息回执。**

1. 登录 Amazon Connect 管理员网站，网址为 https://*instance name*.my.connect.aws/。选择**自定义通信小部件**。  
![\[“配置指南”页面，“自定义通信小部件”选项。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-customize-chat-window-button.png)

1. 选择**编辑**。  
![\[“已保存的通信小部件自定义”页面，“编辑”按钮。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-edit-messagereceipt.png)

1. 默认情况下，不启用**消息回执**。设置为**启用**。  
![\[消息回执选项已启用。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chatwidget-enable-messagereceipt.png)

消息回执现已启用。使用通信小部件的客户将立即开始看到*已送达*和*已读*回执。

# 为聊天参与者设置聊天超时
<a name="setup-chat-timeouts"></a>

当座席和客户之间的聊天对话在一段时间内处于非活动状态（未发送任何消息）时，您可能希望将聊天参与者视为空闲状态，甚至可能希望自动断开座席与聊天的连接。

为此，您可以使用操作配置空闲超时和自动关闭超时。[UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html)

**提示**  
本主题介绍如何为客户与座席的对话设置聊天超时。如果您正在寻找有关在客户与 Lex 互动时配置聊天超时的信息，请参阅[Amazon Connect 流数据块：获取客户输入](get-customer-input.md)数据块的[Lex 互动期间可配置聊天输入的超时时间](get-customer-input.md#get-customer-input-configurable-timeouts-chat)部分。

**您可以设置四种不同类型的计时器。**
+ 您可以制定在采取操作前必须经过的时间。
+ 可以使用任意组合的计时器。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/setup-chat-timeouts.html)

**以分钟为单位指定所有计时器。**
+ 最短：2 分钟
+ 最长：480 分钟（8 小时）

**计时器应用于参与者角色，在聊天过程中一直有效。**
+ 您可以为参与者角色（例如座席和客户）配置计时器，而不是为单个参与者配置计时器。
+  设置计时器后，它们将在聊天过程中一直有效。如果聊天已转移，则计时器将应用于新的 agent/customer 互动。

## 聊天计时器的工作原理
<a name="how-chat-timer-work"></a>

计时器的行为如下所示：
+ 当座席和客户都连接到聊天时，或者当客户和自定义参与者（例如自定义机器人）时，计时器开始计时。
+ 计时器首先在 agent/custom 参与者加入聊天时开始，并在 agent/custom 参与者离开聊天时停止。
+ 如果一个角色同时配置了空闲计时器和自动断开计时器，则空闲计时器会在自动断开计时器之前运行。例如，如果同时配置了两个计时器，只有在参与者被视为空闲之后，自动断开连接计时器才会启动。
+ 如果仅为角色配置了一种类型的计时器，则该计时器会立即启动。
+ 无论参与者在什么时候发送消息，该参与者的计时器都将被重置。如果他们之前被认为处于空闲状态，现在就不再被认为处于空闲状态了。
+ 当向消息添加附件时，聊天计时器会被重置。
+  agent/custom 参与者加入时设置的配置将在参与 agent/custom 者继续聊天时生效。如果您在 agent/custom 参与者和客户已经相互连接的情况下更新计时器配置，则会存储新配置，但除非有新的 agent/custom 参与者连接到聊天，否则不会应用新配置。
+ 发生自动断开事件时，除客户以外的所有参与者（例如座席、任何监控主管或自定义参与者）都将断开连接。如果座席已断开连接，并且已配置 [设置断开连接流](set-disconnect-flow.md) 数据块，则会将此聊天路由到它。

### 闲置计时器到期
<a name="idle-timer-expiry"></a>

以下是客户自定义参与者互动过程中闲置计时器到期时的情况：

1. 空闲事件会分散到所有 websockets/streaming 端点。

1. 如果配置了自动断开计时器，则计时器将启动。

1. 如果聊天联系处于**等待**状态时，闲置计时器到期，则联系不会通过**时间到期**分支进行路由。如果出现这种情况，则不会采取任何操作。

### 自动断开自定义参与者的连接
<a name="auto-disconnecting"></a>

当自动断开计时器到期连接时，自定义参与者会断开与聊天的连接。

当自动断开计时器到期连接时，Amazon Connect 会执行以下步骤之一：

1. 聊天目前位于为自定义参与者配置的 [Wait](wait.md) 数据块中。
   + 自定义参与者会断开与聊天的连接，聊天会通过**断开连接的机器人**参与者分支恢复流。

1. 聊天当前位于为客户配置的 [Wait](wait.md) 数据块中，或者聊天不在**等待**数据块中。
   + 自定义参与者断开与聊天的连接，并且不会采取任何其他操作。

## 向参与者显示的消息
<a name="chat-timeouts-events"></a>

发生以下任一事件时，系统会向所有参与者显示消息：
+ 参与者处于空闲状态。
+ 空闲的参与者发送消息后，就不再处于空闲状态。
+ 连接自动断开。由于座席已断开连接，因此无法看到消息。

这些事件不会保留在记录中，也不会计费。

在联系人控制面板（CCP）中，会向座席显示其中每个事件的默认消息（使用所有支持的语言）。

下图显示了座席在 CCP 中看到的默认空闲消息示例。例如，*座席已处于空闲状态*。

![\[CCP，默认的空闲消息。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/chat-timeout-message.png)


## 推荐用法
<a name="chat-timeouts-usage"></a>

要使用聊天超时功能，建议您执行以下操作：

1. 在联系流的 [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html)Lambda 中嵌入号召性用语。

1. 根据您的用例，可以在开始聊天后（流程开始时）立即放置 Lambda，也可以在将联系人路由到队列之前放置 Lambda。

## 为断开连接事件自定义客户的聊天用户界面
<a name="chat-timeouts-ui"></a>

要针对断开连接事件自定义客户的聊天用户界面，请参阅 [ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs) 中的以下方法：
+ `onParticipantIdle(callback)`
+ `onParticipantReturned(callback)`
+ `onAutoDisconnection(callback)`

使用这些方法注册在新事件到达时触发的回调处理程序。

# 为移动聊天启用推送通知
<a name="enable-push-notifications-for-mobile-chat"></a>

移动聊天的推送通知是通过 [AWS End User Messaging](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-service.html) 配置的。您可以在 iOS 或 Android 设备上为移动聊天启用推送通知，这样即使客户没有主动使用您的移动应用程序，您也可以提醒他们注意新消息。您可以在与[Amazon Connect 移动设备 SDKs](https://docs.aws.amazon.com/connect/latest/adminguide/integrate-chat-with-mobile.html)、[Webview 解决方案或自定义原生解决方案](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples)集成的现有应用程序中启用此功能。

 以下步骤和资源将帮助您开始将 Amazon Connect 推送通知集成到原生移动应用程序中：

## 第 1 步：从苹果 APNs 和谷歌的 FCM 控制台获取凭证
<a name="step-1-enable-push-notifications-for-mobile-chat"></a>

要进行设置 Amazon Connect 使其能够向您的应用程序发送推送通知，您首先必须从 Apple APNs 和 Google 的 FCM 控制台获取凭据，以便[AWS 最终用户消息](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-service.html)将通知发送到您的移动应用程序。您提供的凭证取决于您使用的推送通知系统：
+  有关 Apple 推送通知服务 (APNs) 凭据，请参阅 Apple 开发者文档中的 “[从 Apple 获取加密密钥和密钥 ID](https://developer.apple.com/documentation/usernotifications/establishing-a-token-based-connection-to-apns#Obtain-an-encryption-key-and-key-ID-from-Apple)[” 和 “从 Apple 获取提供商证书](https://developer.apple.com/documentation/usernotifications/establishing-a-certificate-based-connection-to-apns#Obtain-a-provider-certificate-from-Apple)”。
+  对于可以通过 Firebase 控制台获取的 Google 的 Firebase Cloud Messaging（FCM）凭证，请参阅 [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)。

## 步骤 2：使用 AWS 控制台创建AWS 最终用户消息服务应用程序并启用 FCM 的推送通知渠道或 APNs
<a name="step-2-enable-push-notifications-for-mobile-chat"></a>

 在您能够启用 Amazon Connect 发送推送通知之前，首先必须在 [AWS 控制台](https://console.aws.amazon.com/push-notifications/)中[创建AWS End User Messaging 应用程序并启用推送通知](https://docs.aws.amazon.com/push-notifications/latest/userguide/procedure-enable-push.html)渠道。

 按照以下说明创建应用程序并启用任何推送渠道。要完成此过程，您只需输入应用程序名称即可。您可以稍后启用或禁用任何推送渠道：

1.  打开 “ AWS 最终用户消息推送” 控制台，网址为 [https://console.aws.amazon.com/push-notifications/](https://console.aws.amazon.com/push-notifications/) 

1.  选择**创建应用程序**。

1.  在**应用程序名称**中，输入您的应用程序名称。

1.  （可选）按照此可选步骤启用 **Apple 推送通知服务（APNs）**。

   1.  对于 **Apple 推送通知服务 (APNs)**，请选择 “**启用**”。

   1.  对于**默认身份验证类型**，选择以下任一选项：

      1.  如果您选择**密钥凭证**，请提供您的 Apple 开发者帐户中的以下信息。 AWS 最终用户消息推送需要此信息来构造身份验证令牌。

         1.  **密钥 ID** – 分配给您的签名密钥的 ID。

         1.  **捆绑包标识符** – 分配给您的 iOS 应用程序的 ID。

         1.  **团队标识符** – 分配给您的 Apple 开发人员账户团队的 ID。

         1.  **身份验证密钥** – 当您创建身份验证密钥时从您的 Apple 开发人员账户下载的 .p8 文件。

      1.  如果您选择**证书凭证**，请提供以下信息：

         1.  **SSL 证书** – 您的 TLS 证书的 .p12 文件。

         1.  **证书密码** – 如果您向证书分配了密码，请在此处输入。

         1.  **证书类型** - 选择要使用的证书类型。

1.  （可选）按照此可选步骤启用 **Firebase Cloud Messaging（FCM）**。

   1.  对于 **Firebase Cloud Messaging（FCM）**，选择**启用**。

   1.  对于**默认身份验证类型**，选择**令牌凭证**，然后选择您的服务 JSON 文件。

1.  选择**创建应用程序**。

## 步骤 3：将 AWS 最终用户消息应用程序与 Amazon Connect 实例关联
<a name="step-3-enable-push-notifications-for-mobile-chat"></a>

 要在[Amazon Connect 实例](https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html)上启用推送通知，您需要通过调用 [CreateIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html)API 将 AWS 最终用户消息应用程序与[Amazon Connect 实例](https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html)关联起来`PINPOINT_APP`[IntegrationType](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html#API_CreateIntegrationAssociation_RequestSyntax)。对于任何支持的语言，您可以使用 [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/connect/create-integration-association.html) 或 [Amazon Connect SDK](https://aws.amazon.com/developer/tools/) 调用此 API。这是 AWS 最终用户消息应用程序和 Amazon Connect 实例之间的每次集成都需要一次性入门步骤。

## 第 4 步：使用 FCM 或 APNs SDK 获取设备令牌，然后将其注册到 Amazon Connect
<a name="step-4-enable-push-notifications-for-mobile-chat"></a>

您需要获取设备令牌，并使用它向 Amazon Connect 聊天联系人注册最终用户移动设备，以便在聊天中发送新消息的推送通知。 阅读以下 FCM/APNs 开发者文档，了解如何从移动应用程序生成和获取设备令牌。
+  有关 Apple 推送通知服务 (APN)，请参阅 Apple 开发者文档 APNs中的[注册应用程序](https://developer.apple.com/documentation/usernotifications/registering-your-app-with-apns)。
+  有关 Firebase Cloud Messaging（FCM），请参阅 [FCM 注册令牌管理的最佳实践](https://firebase.google.com/docs/cloud-messaging/manage-tokens)。

 要向聊天联系注册设备，建议您执行以下操作：

1.  当移动应用程序调用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 时，将`deviceToken`和`deviceType`作为[联系人属性](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-Attributes)传递。对于 WebView 和托管通信小部件用户，请参阅[如何将联系属性传递到通信小部件](https://docs.aws.amazon.com/connect/latest/adminguide/pass-contact-attributes-chat.html#how-to-contact-attributes-chatwidget)以了解更多详细信息。

1.  在联系流的 Lambda 函数中嵌入[CreatePushNotificationRegistration](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html)操作调用。该流数据块应从用户定义的联系属性中读取 `deviceToken` 和 `deviceType`，从系统属性中读取 `initialContactId`，然后将这些值传递给 Lambda 函数。

   1.  根据您的使用案例，如果您希望最终用户立即接收推送通知，请在开始聊天后（在流开始时）立即放置 Lambda 函数，或者在将联系人路由到队列之前放置 Lambda 函数，以便他们仅在座席即将加入时才接收联系人。API 调用完成后，当座席或系统发出新消息时，设备将开始接收推送通知。默认情况下，将为所有系统和座席消息发送推送通知。  
![\[在 Amazon Connect 管理员网站流设计器中调用 Lambda 函数流数据块。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/step-4-set-up-push-notifications-for-mobile-chat-1.png)

1.  （可选）在流程的 Lambda 函数中嵌入对[DeletePushNotificationRegistration](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html)操作的调用。API 调用完成后，当座席或系统发出新消息时，设备将停止接收推送通知。

## 第 5 步：在移动应用程序上接收推送通知
<a name="step-5-enable-push-notifications-for-mobile-chat"></a>

 请查看我们的[Amazon Connect 聊天界面示例](https://github.com/amazon-connect/amazon-connect-chat-ui-examples)项目，并参考我们的 [iOS](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/iOS-WKWebView-sample) 和 [Android](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples/android-webview-sample) 聊天网络视图示例，这些示例展示了如何集成 Amazon Connect APIs 到加入和接收推送通知。

## 监控推送通知的使用情况
<a name="monitor-your-usage-for-push-notification"></a>

 为了确保推送通知的可靠性、可用性和性能，监控推送通知的使用情况至关重要。您可以通过多种渠道跟踪这些信息：

1.  AWS 为推送通知提供全面的监控工具。 有关更多信息，请参阅[监控 AWS 最终用户消息推送](https://docs.aws.amazon.com/push-notifications/latest/userguide/monitoring-overview.html)。

1.  根据您使用的推送通知服务，您可以通过相应的控制台访问其他使用情况数据。

   1.  Firebase Cloud Messaging（FCM）：请查阅 FCM 文档中的[了解消息传送](https://firebase.google.com/docs/cloud-messaging/understand-delivery?platform=android)部分，以了解您的 FCM 使用情况。

   1.  Apple 推送通知服务 (APNs)：查看有关[使用指标查看推送通知状态的 APNs文档部分 APNs，并](https://developer.apple.com/documentation/usernotifications/viewing-the-status-of-push-notifications-using-metrics-and-apns)监控您的通知状态。

# 让客户能够在 Amazon Connect 中恢复聊天对话
<a name="chat-persistence"></a>

客户通常会开始聊天，然后离开对话，稍后再回来继续聊天。这种情况可能会在几天、几个月甚至几年的时间里多次发生。为了支持此类长时间的聊天，您可以启用持续聊天功能。

通过持续聊天，客户可以继续之前的对话，同时保留上下文、元数据和转录。客户回到聊天时无需重复之前的话，座席可以访问整个对话历史记录。

## 聊天补充
<a name="rehydration"></a>

持续聊天是通过一种称为聊天补充的过程实现的。此过程允许从以前的聊天联系中检索聊天记录并显示出来。它使客户和座席可以轻松地从他们中断的地方继续对话。

**重要**  
只有已结束的聊天会话才会被允许用于补充新的聊天会话，因为转录生成是异步进行的。  
用户应等待 30-60 秒，然后再尝试从之前结束的聊天中进行补充。

Amazon Connect 支持两种类型的补液：
+ `ENTIRE_PAST_SESSION`：开始新的聊天会话，并补充过去聊天会话中的所有聊天片段。
+ `FROM_SEGMENT`：开始新的聊天会话，并补充指定的过去的聊天片段。

有关显示这些不同补充模式的用例示例，请参阅[使用案例示例](#persistentchatscenario)。

## RelatedContactId
<a name="relatedcontactid"></a>

新联系可以通过 `RelatedContactId` 与现有联系建立关联。此新联系人包含相关联系人的[联系属性](connect-attrib-list.md)副本。

有关 `RelatedContactId` 如何在联系记录中建模的更多信息，请参阅 [Amazon Connect 联系记录的数据模型](ctr-data-model.md)。

对于持续聊天，`RelatedContactId` 描述了用于获取聊天补充的 `contactId`。

## 如何启用持续聊天
<a name="enable-persistent-chat"></a>

有两种方法可以启用持续聊天：
+ 创建新聊天时指定以前的联系 ID。有关说明，请参阅[在创建新的聊天联系时启用持续聊天](#enable-persistent-chat-creating-new-chat-contact)。
+ 将[创建持久联系人关联](create-persistent-contact-association-block.md)数据块添加到流中。有关说明，请参阅[在流中启用持续聊天](#enable-persistent-chat-within-contact-flow)。

**注意**  
您可以选择任意一种方法来保留聊天，但不能两者兼而有之。也就是说，您只能在新聊天中根据 `SourceContactID` 启用一次持续聊天。

要提供持续的聊天体验，您需要在开始新聊天或使用[创建持续联系关联](create-persistent-contact-association-block.md)流数据块时提供以前的联系 ID。此操作不会为您自动执行。建议您创建一个存储库来存储联系记录数据。通过存储库，可以检索每位客户的这些数据。

 有两种方法可以在存储库中创建条目：
+ [使用聊天消息流](https://docs.aws.amazon.com/connect/latest/adminguide/chat-message-streaming.html)在聊天结束时创建条目。
+ 检查[联系人事件](https://docs.aws.amazon.com/connect/latest/adminguide/contact-events.html#contact-events-data-model)，并使用 [AWS Lambda 功能](https://docs.aws.amazon.com/connect/latest/adminguide/connect-lambda-functions.html)在存储库中创建条目。

设置存储库后，您可以检索客户以前的联系 ID，并在开始新聊天时或在[创建持续联系关联](create-persistent-contact-association-block.md)流数据块中提供该联系 ID。

此外，确保可以从实例的 Amazon S3 存储桶中检索过去的聊天记录。以下两点会导致 Amazon Connect 无法检索文字记录，也无法让聊天持续进行：
+ 您使用多个聊天文字记录存储桶。
+ 您可以更改 Amazon Connect 生成的聊天文字记录文件名。

### 在创建新的聊天联系时启用持续聊天
<a name="enable-persistent-chat-creating-new-chat-contact"></a>

要在创建新的聊天联系人时设置持续的聊天体验，请在 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 的`SourceContactId`参数`contactId`中提供前面的内容。这样就可以对以前联系人的聊天文字记录进行补充。客户和座席都可以在聊天中看到文字记录。有关示例，请参阅[使用案例示例](#persistentchatscenario)。

### 在流中启用持续聊天
<a name="enable-persistent-chat-within-contact-flow"></a>

要在流中设置持续聊天体验，请执行以下操作：

1. 创建聊天联系后，在流中添加[创建持久联系关联](create-persistent-contact-association-block.md)数据块。

1. 使用用户定义的属性指定源联系 ID。

或者，您可以使用 [CreatePersistentContactAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreatePersistentContactAssociation.html)API 提供来源联系人 ID，使当前聊天保持不变。

使用流数据块或 API 时，补充会在聊天开始后启动。补充完成后会发出补充事件通知您。

## 使用案例示例
<a name="persistentchatscenario"></a>

例如，客户开始了一个聊天会话：

1. 座席 a1 接受了聊天，客户和座席 a1 开始对话。这是在当前聊天会话中创建的第一个联系人。例如，`contactId` **C1** 可能是 11111111-aaaa-bbbb-1111-1111111111111。

1. 然后，座席 a1 将聊天转给座席 a2。这将创建另一个联系人。例如，`contactId` **C2** 可能是 2222222-aaaa-bbbb-2222-222222222222222。

1. 座席 a2 结束了聊天。

1. 客户会被转至断开连接流，进行聊天后调查，从而创建另一位联系人。例如，`contactId` **C3** 可能是 33333333-aaaa-bbbb-3333-3333333333333。

1. 显示聊天后调查，聊天会话结束。

1. 后来，客户又回来了，想要恢复过去的聊天会话。

目前，客户可能有两种不同的应用场景。以下是客户的持续聊天用例，以及您如何配置 Amazon Connect 以提供这些用例。

### 应用场景 1
<a name="persistentchatscenario-usecase1"></a>

客户想继续过去的聊天会话，但他们希望隐藏聊天后调查。您可以使用以下配置来提供这种体验。

**请求:**

```
PUT /contact/chat HTTP/1.1
Content-type: application/json
{
   "Attributes": { 
      "string" : "string" 
   },
   "ContactFlowId": "string",
   "InitialMessage": { 
      "Content": "string",
      "ContentType": "string"
   },
   "InstanceId": "string",
   ... // other chat fields
     
   // NEW Attribute for persistent chat 
   "PersistentChat" : {
       "SourceContactId":"2222222-aaaa-bbbb-2222-222222222222222" 
       "RehydrationType":"FROM_SEGMENT"
   }
}
```

#### 配置
<a name="usecase1-configuration"></a>
+ SourceContactId = 2222222-aaaa-bbbb-222222222222222（C2 的联系人 ID）
+ RehydrationType = "`FROM_SEGMENT`"

#### 预期行为
<a name="usecase1-behavior"></a>
+ 此配置会从指定的过去已结束联系人 C2（例如 2222222-aaaa-bbbb-2222-222222222222222）启动持续聊天会话。

  可以在当前的持续聊天会话中访问过去聊天会话 C2 (2222222-aaaa-bbbb-2222-222222222222222) 和 C1 (11111111-aaaa-bbbb-1111-1111111111111) 的记录。请注意，聊天片段 C3 (33333333-aaaa-bbbb-3333-3333333333333) 已从持续聊天会话中删除。
+ 在本例中，[StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)响应将 C2（2222222-aaaa-bbbb-222222222222222）返回为 “”。ContinuedFromContactId
+ 这个持续聊天会话的 `RelatedContactId` 是 2222222-aaaa-bbbb-2222-222222222222222 (C2)。

### 应用场景 2
<a name="persistentchatscenario-usecase2"></a>

客户想继续过去的聊天会话，并查看过去整个参与过程的记录（他们不想隐藏聊天后调查）。您可以使用以下配置来提供这种体验。

**注意**  
 对于 `ENTIRE_PAST_SESSION` 补充类型，请将过去聊天会话的第一个联系人（初始 `contactId`）指定为 `SourceContactId` 属性。

**请求:**

```
PUT /contact/chat HTTP/1.1
Content-type: application/json
{
   "Attributes": { 
      "string" : "string" 
   },
   "ContactFlowId": "string",
   "InitialMessage": { 
      "Content": "string",
      "ContentType": "string"
   },
   "InstanceId": "string",
   ... // other chat fields
     
   // NEW Attribute for persistent chat 
   "PersistentChat":{
        "SourceContactId":"11111111-aaaa-bbbb-1111-1111111111111" // (first contactId C1)
        "RehydrationType":"ENTIRE_PAST_SESSION"
   }
}
```

#### 配置
<a name="usecase2-configuration"></a>
+ SourceContactId = `11111111-aaaa-bbbb-1111-1111111111111` (C1)
+ RehydrationType = “E`NTIRE_PAST_SESSION`”

#### 预期行为
<a name="usecase2-behavior"></a>
+ 这会从最近结束的聊天联系 (C3) 启动持续聊天会话。可以在当前的持续聊天会话中访问过去聊天会话 C3、C2 和 C1 的记录。
+ 在本例中，[StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)响应以 “” 的形式返回 33333333-aaaa-bbbb-3333-33333333333 (C3)。ContinuedFromContactId
+ 这个持续聊天会话的 `RelatedContactId` 是 33333333-aaaa-bbbb-3333-3333333333333 (C3)。

**注意**  
聊天联系是可以累积的。聊天会话关联后，它们会继续进行下去。  
例如，如果将属于过去聊天会话的联系人 (`contactId` C2) 链接到过去不同聊天会话的联系人 (`contactId` C1)，那么通过链接 C2 创建的新持续聊天会话也会导致 C1 的隐式链接。新的持续聊天会话将具有以下关联：C3 → C2 → C1  
过去的 ContactID（持续聊天会话从中继续）会显示在 API 响应`ContinuedFromContactId`的字段中[StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)。它也在联系人的联系记录[ContactTraceRecord](ctr-data-model.md#ctr-ContactTraceRecord)中的 RelatedContactId 字段中。

## 如何访问持续聊天的过去聊天联系记录
<a name="access-past-chat-transcript"></a>

使用现有的 `NextToken` 分页模型访问持续聊天的过去聊天记录。如果存在过去的聊天消息，则在新启动的持续聊天会话`NextToken`中对的初始呼叫会在响应中包含。[GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) `NextToken`必须用于访问过去的聊天记录，同时`BACKWARD`在后续[GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html)通话中`ScanDirection`将其设置为，以获取过去的聊天消息。

如果过去有多条聊天消息，则[GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html)返回一条新的聊天记录，`NextToken`并且可以重复相同的过程来获取更多过去的聊天记录。

## 不支持：使用 `StartPosition` 和 `contactId` 筛选器进行持续聊天
<a name="startposition"></a>

Amazon Connect 不支持在[GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html)呼叫时使用`StartPosition`和`contactId`过滤来自过去聊天的笔录项目属性。

# 在 Amazon Connect 中启用实时聊天消息流
<a name="chat-message-streaming"></a>

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 的工作原理
<a name="how-chat-message-streaming-apis-work"></a>

当 [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 主题
<a name="step1-chat-streaming"></a>

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 步：启用聊天联系
<a name="step2-chat-streaming"></a>

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 步：对联系启用消息流
<a name="step3-chat-streaming"></a>
+ 致电[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 步：创建参与者连接
<a name="step4-chat-streaming"></a>
+ [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` 成功连接到聊天联系，则此步骤（创建参与者连接）为可选。

## 后续步骤
<a name="nextsteps-chat-streaming"></a>

你已经准备好处理消息流 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 有效载荷
<a name="sns-payload"></a>

成功启用消息流后，您可能需要筛选消息，以便将其发送给目标参与者：座席、客户或所有人。

要按参与者进行筛选，请阅读 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 服务本身。

## 有效负载中的消息属性
<a name="sns-message-attributes"></a>

以下是对 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 有效负载示例
<a name="sns-message-payload"></a>

```
{
  "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 中消息流的问题
<a name="troubleshoot-message-streaming"></a>

## 消息未发布到 SNS
<a name="message-not-published-to-sns"></a>

发生这种情况时，建议您检查 [第 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 服务主体授予加密和解密权限。

## 流式传输无法启动
<a name="contact-flow-not-starting"></a>

如果您使用消息流 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)。这样可以确保在您确认客户已准备好接收消息后发送消息。

## 问题仍未解决？
<a name="other-issues-message-streaming"></a>

如果在尝试了之前的解决方案后仍然存在消息流问题，请联系 支持 寻求帮助。

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)。
+ 您所在区域。
+ 问题的详细说明。

# 通过集成自定义参与者，在 Amazon Connect 中自定义聊天流体验
<a name="chat-customize-flow"></a>

您可以将其他解决方案（例如自动程序）与 Amazon Connect 聊天集成，以创建自定义的聊天流体验。

以下概述了如何自定义聊天流体验。聊天对话开始后，为每个聊天分段实施这些步骤。我们建议在聊天流程 APIs 中添加一个[AWS Lambda 函数](invoke-lambda-function-block.md)区块来调用。

**重要**  
在 [AWS Lambda 函数](invoke-lambda-function-block.md) 数据块之前添加一个 [播放提示](play.md) 数据块。只有当 **Invoke AWS Lambda** 区块是入站聊天流程中的第一个区块时，才需要这样做。

1.  [启用实时聊天消息流](chat-message-streaming.md)。

1. 调用 Amazon Connect [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html)API 为聊天联系人添加自定义参与者 (`ParticipantRole`=`CUSTOM_BOT`)。

   1. 有关如何创建用于调用 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. 保留从`ParticipantToken`中获得的[CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html)来电[CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)。 `CreateParticipantConnection`返回 a`ConnectionToken`，您可以使用它来呼叫其他 Amazon Connect 参与者 APIs。

      致电[CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)为自定义参与者创建连接时：
      + 将 `ConnectParticipant` 设置为 `True`，可将自定义参与者标记为已连接，以进行消息流式传输。
      + 通过致电后续`Type``CONNECTION_CREDENTIALS`的 Amazon Connect 参与者服务 APIs。
      + 应在调用 `CreateParticipant` 后的 15 秒内调用 `CreateParticipantConnection`。

1. 将参与者添加到联系人后，他们可以使用 Amazon Connect 参与者服务与客户交换消息 APIs。

1. 要断开参与者的连接，请调用 [ DisconnectParticipant](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_DisconnectParticipant.html)API。

**注意**  
如果联系人已有座席或 Amazon Lex 自动程序，则无法将自定义参与者添加到聊天中。
当座席或 Amazon Lex 自动程序加入联系人时，自定义参与者将断开连接。
一个联系人只能有一个自定义参与者。
不允许自定义参与者访问客户可能上传的附件。

建议配置自定义参与者可以与联系人聊天的时长：
+ 为 `ParticipantRole` = `CUSTOM_BOT` 设置 [Wait](wait.md) 数据块上的 **Timeout** 属性。
+ 如果自定义自动程序参与者在超时之前没有断开连接，该联系人将被路由到**已超时**分支。这样，您就可以决定接下来运行哪个数据块来解决客户的查询了。

**注意**  
如果联系人被路由到**已超时**分支，他们就不会断开与该联系人的连接。您必须调用 [ DisconnectParticipant](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_DisconnectParticipant.html)API 才能断开参与者的连接。

## 为加入自定义参与者的客户激活计时器
<a name="integrate-bot-extension-client"></a>

您可以为加入自定义参与者（例如自定义机器人）的客户激活计时器。这样，您就能检测到客户何时停止回复，从而终止机器人对话，并执行流中的下一步。通过终止空闲参与者，您可以减少客户与自定义参与者之间无响应的未完成聊天次数。

执行以下步骤集成空闲参与者自定义机器人扩展，并可选择设置自定义计时器值。这些步骤假定您已经在聊天中使用了自定义参与者功能。

1. 在自定义参与者加入聊天之前，请为客户调用 [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html)API。

   1. 计时器仅为客户激活。自定义参与者没有空闲参与者或自动断开连接的计时器。

   1. 您可以选择调用 API 的方法。

   1. 在此步骤中配置的计时器值将在聊天过程中一直有效。如果您要为**客户和座席互动**设置不同的计时器值，请参阅步骤 2。

   1. 如果您已经以这种方式设置了客户端，则无需执行任何其他操作即可集成自定义参与者。

1. （可选）要配置在**客户和座席互动**期间与**客户和自定义参与者互动**期间不同的计时器和计时器值：
   + 在代理加入聊天之前，请使用所需的配置再次调用 [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html)API。

有关聊天时间的更多信息，请参阅 [为聊天参与者设置聊天超时](setup-chat-timeouts.md)。

### 启动计时器
<a name="starting-timers"></a>

自定义参与者使用 [CreateParticipantConnection](https://docs.aws.amazon.com/connect/latest/APIReference/API_connect-participant_CreateParticipantConnection.html)API 与客户建立连接后，他们将开始计时器。

### 当不兼容的参与者加入自定义参与者的聊天时会发生什么情况
<a name="non-compatible-participants"></a>

以下是座席或 Lex 机器人参与者加入与自定义参与者的聊天并且他们是不兼容的参与者时会发生的情况：

1. 自定义参与者将自动断开聊天连接。

1. 所有先前处于活动状态的计时器都将终止，并为连接的参与者创建新的计时器（如果配置了计时器）。

1. 每个新的计时器也会更新最新配置（如果需要）。这实际上是为新的聊天活跃参与者建立一个新的“闲置会话”。

### 与等待区块计时器的互动
<a name="interaction-wait-block-timer"></a>

闲置计时器不会影响 [Wait](wait.md) 区块的运行。

聊天联系进入**等待**区块时启动的**等待**区块计时器会继续运行。如果**等待**区块计时器过期，则无论是否有闲置参与者计时器处于活动状态，联系都会恢复流，并顺着**时间已过期**分支向下传送。

## 问题排查技巧
<a name="ts-chat-custom-bot"></a>
+ `ResourceNotFoundException`: 

  如果您在调用 `CreateParticipantConnection` API 时收到自定义参与者的 `ResourceNotFoundException`，请检查是否在 `CreateParticipant` API 调用后 15 秒内调用了 `CreateParticipantConnection` API。
+ `AccessDeniedException`: 

  如果您收到 `AccessDeniedException` 错误并且参与者角色为 CUSTOM\$1BOT，则表示机器人正在尝试访问附件。不允许 CUSTOM\$1BOT 的参与者角色访问客户上传的附件。

# 在 Amazon Connect 中为聊天联系设置客户身份验证
<a name="customer-auth"></a>

您可以在聊天中提示客户登录并进行身份验证。例如，与聊天机器人互动的未通过身份验证的客户在被路由到座席之前，系统会提示他们先登录。

此内置功能利用了 Amazon Connect Customer Profiles 和 [Amazon Cognito](https://aws.amazon.com/cognito/)。使用 Customer Profiles 不会产生额外费用，如果您在设置过程中选择了默认设置，则已在您的 Amazon Connect 实例中[启用](enable-customer-profiles.md)了 Customer Profiles。有关 Amazon Cognito 定价的信息，请参阅 [Amazon Cognito 定价](https://aws.amazon.com/cognito/pricing/)页面。

为聊天设置客户身份验证：

1. 为您的 Amazon Connect 实例[启用客户身份验证](enable-connect-managed-auth.md#enable-customer-auth)。

1. [启用身份验证消息](enable-connect-managed-auth.md#enable-auth-message).

1. 将 [验证客户身份](authenticate-customer.md) 数据块添加到流中。

如果您的联络中心正在使用 Amazon Connect 外部的现有身份验证解决方案，请参阅[聊天前身份验证](pre-chat-auth.md)。

# 为托管的通信小部件启用客户身份验证
<a name="enable-connect-managed-auth"></a>

本主题将介绍如果您使用 Amazon Connect 托管的聊天通信小部件，如何设置身份验证。您为 Amazon Connect 实例启用了客户身份验证，然后启用了一条身份验证消息，该消息显示一个链接，点击后会弹出 Amazon Cognito 托管 UI。

## 所需的 IAM 策略
<a name="auth-page-iam-policies"></a>

如果您使用自定义 IAM 策略来管理对 Amazon Connect 控制台的访问权限，请参阅[自定义 IAM 策略所需的权限](security-iam-amazon-connect-permissions.md)以获取访问**客户身份验证**页面所需权限的列表。

## 在您的 Amazon Connect 实例中启用客户身份验证
<a name="enable-customer-auth"></a>

1. 打开 Amazon Connect 控制台，网址为[https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/)。

1. 在“实例”页面上，选择实例别名。实例别名也是您的**实例名称**，该名称显示在您的 Amazon Connect URL 中。下图显示了 **Amazon Connect 虚拟联系中心实例**页面，其中，实例别名周围有一个方框。  
![\[“Amazon Connect 虚拟联络中心实例”页面，实例别名。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/instance.png)

1. 在左侧导航菜单上，选择**应用程序**、**客户身份验证**。如果您没有看到此选项，则该选项可能在您所在的 AWS 地区不可用。有关客户身份验证可用区域的信息，请参见[按区域显示的客户身份验证可用性](regions.md#customerauthentication_region)。

1. 在**客户身份验证**页面上，选择**在 Amazon Cognito 中创建用户池**。这样可打开 Amazon Cognito 控制台。

1. 使用您的身份提供商创建新的用户池。有关说明，请参阅《Amazon Cognito 开发人员指南》**中的[用户池入门](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-user-pools.html)。
**注意**  
当您配置 Amazon Cognito 应用程序客户端时，必须选择**不生成客户端密钥**。只支持不带客户端密钥的 Amazon Cognito 应用程序客户端。有关更多信息，请参阅《Amazon Cognito Developer Guide》**中的 [Application-specific settings with app clients](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html)。

1. 在创建 Amazon Cognito 用户池后，返回到**客户身份验证**页面，然后选择**关联用户池**。

1. 在**用户池**部分，从下拉菜单中选择您创建的用户池，然后选择**确认**。

   这样会将用户池关联到您的 Amazon Connect 实例。它使[验证客户身份](authenticate-customer.md)流数据块能够访问用户池。

1. 继续执行下一步：[启用身份验证消息](#enable-auth-message)。

## 启用身份验证消息
<a name="enable-auth-message"></a>

要启用身份验证消息，请在代码片段末尾添加身份验证参数片段变量。有关添加片段变量的信息，请参阅[Amazon Connect 中支持可自定义的小部件片段字段](supported-snippet-fields.md)。以下代码是您需要添加的身份验证参数片段的示例。

```
amazon_connect('authenticationParameters', { 
    redirectUri: 'your_redirect_url', // https://example.com 
    identityProvider: 'your_identity_provider_name' //optional
 });
```

其中：
+ `redirectUri` 是您在 IdP（身份提供商）和 Amazon Cognito 中配置的重定向 URI。这是您的客户登录后自动定向之处。在此页面中，您可以检查网址参数，如果有代码和状态，则可以使用这些值调用 [UpdateParticipantAuthentication](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantAuthentication.html)API。API 调用完成后，关闭弹出窗口；客户将返回聊天体验。
+ `identityProvider` 是您在 Amazon Cognito 中配置的身份提供商名称。该字段是可选的。如果提供了一个值，则登录链接会自动将客户引导到身份提供商的登录页面，而不是 Amazon Cognito 管理的登录页面，客户在该页面上需要选择用于登录的身份提供商。

 当流到达[验证客户身份](authenticate-customer.md)数据块时，您可以注册回调并将状态存储在本地，以便在重定向 URI 中进行验证，如下面的示例代码片段中所示：

```
amazon_connect('registerCallback', {
       'AUTHENTICATION_INITIATED' : (eventName, data) => {
            console.log(data.state)
        },
      });
```

启用客户身份验证后，在流中添加一个[验证客户身份](authenticate-customer.md)数据块。此数据块可在流中对聊天联系进行身份验证，并根据身份验证结果将他们引导到特定路径。

# 使用 Amazon Connec StartChatContact t API 进行聊天前身份验证
<a name="pre-chat-auth"></a>

在开始聊天之前在您的网站或移动应用程序中进行身份验证的客户可以在聊天启动时被识别为已通过身份验证。你可以使用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 来做到这一点。

经过身份验证的客户开始聊天后，使用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html)API 中的参数设置他们的状态，如以下代码片段所示：

```
"SegmentAttributes": {
    "connect:CustomerAuthentication" : { 
        "ValueMap": {
            "Status": {
                "ValueString": "AUTHENTICATED"
            }
        }
    },
    "CustomerId": "12345"
```

`CustomerId` 是用于识别客户的可选字段。它可以是 Amazon Connect Customer Profiles ID，也可以是来自外部系统（例如 CRM）的自定义标识符。

# 为 AI 支持的聊天启用消息流
<a name="message-streaming-ai-chat"></a>

Amazon Connect 支持用于人工智能驱动的聊天互动的消息流。来自 AI 代理的响应在生成时会逐渐出现，从而改善了对话期间的客户体验。

以下是集成选项以及每个选项的功能：
+ Amazon Connect 座席
  + 消除了 Amazon Lex 的超时限制
  + 在处理过程中提供配送消息（例如 “稍等片刻，我正在审核您的账户”）
  + 使用渐进式文本（渐进式文本气泡）显示部分回复
+ 通过 Amazon Lex 或 Lambda 的第三方机器人
  + 消除了 Amazon Lex 的超时限制
  + 标准机器人响应行为

从 2025 年 12 月开始创建的实例将自动选择使用此功能。对于现有实例，您必须使用 API 或通过控制台手动启用消息流。

## 使用 API 启用消息流
<a name="message-streaming-enable-api"></a>

使用 [UpdateInstanceAttribute](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateInstanceAttribute.html)API 启用消息流式传输。将 `MESSAGE_STREAMING` 属性设置为 `true`。

```
aws connect update-instance-attribute \
  --instance-id your-instance-id \
  --attribute-type MESSAGE_STREAMING \
  --value true
```

要选择退出，请将属性设置为`false`。

## 使用控制台启用消息流
<a name="message-streaming-enable-console"></a>

对于新创建的实例，消息流默认处于启用状态。

对于现有实例：

1. 打开 Amazon Connect 控制台并选择您的实例。

1. 在导航窗格中，选择 Fl **ow** s > **Amazon Lex 机器人**。

1. 在 **Lex 机器人配置**下，选择在 **Amazon Connect 中启用消息流**。

**注意**  
当您使用控制台启用消息流时，所需的`lex:RecognizeMessageAsync`权限会自动添加到基于机器人别名资源的策略中。使用 API 时，必须手动添加此权限。

![\[在 Amazon Connect 控制台中启用消息流选项。\]](http://docs.aws.amazon.com/zh_cn/connect/latest/adminguide/images/message-streaming-ai-chat-enablement.png)


## 更新 Lex 机器人权限
<a name="message-streaming-lex-permissions"></a>

启用消息流后，Amazon Connect 需要获得调用 Amazon Lex API 的权限：

```
lex:RecognizeMessageAsync
```

您必须为 Amazon Connect 实例使用的每个 Amazon Lex 机器人别名更新基于资源的策略。

### 何时更新机器人基于资源的政策
<a name="message-streaming-when-to-update"></a>
+ **新实例** — 默认情况下，任何新关联的 Amazon Lex 机器人别名都将包含在其别名策略`lex:RecognizeMessageAsync`中。
+ **包含现有机器人的现有实**例 — 如果该实例以前使用过 Amazon Lex，并且您现在启用了消息流，则必须更新所有关联的 Amazon Lex 机器人别名的基于资源的策略以包含新的权限。

### Lex bot 别名基于资源的策略的示例片段
<a name="message-streaming-rbp-example"></a>

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "connect-us-west-2-MYINSTANCEID",
      "Effect": "Allow",
      "Principal": {
        "Service": "connect.amazonaws.com"
      },
      "Action": [
        "lex:RecognizeMessageAsync",
        "lex:RecognizeText",
        "lex:StartConversation
      ],
      "Resource": "arn:aws:lex:us-west-2:123456789012:bot-alias/MYBOT/MYBOTALIAS",
      "Condition": {
        "StringEquals": {
          "AWS:SourceAccount": "123456789012"
        },
        "ArnEquals": {
          "AWS:SourceArn": "arn:aws:connect:us-west-2:123456789012:instance/MYINSTANCEID"
        }
      }
    }
  ]
}
```

您可以通过调用 Amazon Lex [UpdateResourcePolicy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UpdateResourcePolicy.html)API 来更新基于资源的 Amazon Lex 机器人别名策略来添加此权限，使其包含针对 Amazon Connect 实例 ARN 资源的`lex:RecognizeMessageAsync`操作。

**重要**  
此功能目前不支持分支回同一个[Amazon Connect 流数据块：获取客户输入](get-customer-input.md)流程块，也不支持在另一个 “**获取客户输入**” 区块中重复使用具有相同别名的 Amazon Lex 机器人。取而代之的是，使用不同的 Amazon Lex 机器人别名创建一个新的 “**获取客户意见**” 区块。

## 超时限制
<a name="message-streaming-timeout-limits"></a>

以下超时限制适用于聊天体验：
+ **标准聊天体验**-超时 10 秒
+ **聊天直播** — 60 秒超时

# 启用动态敏感数据编辑和消息处理
<a name="redaction-message-processing"></a>

Amazon Connect 支持消息处理，即在聊天消息到达任何参与者之前对其进行拦截和修改。该功能支持自动编辑敏感数据和自定义消息处理，从而帮助企业保持合规性和安全标准。

以下是处理选项以及每个选项的功能：
+ 内置敏感数据修改
  + 自动检测并删除信用卡号、社会保险号和其他 PII
  + 支持多种语言，包括英语、法语、葡萄牙语、德语、意大利语和西班牙语变体。有关 Contact Lens 加密功能支持的语言列表，请参阅[Amazon Connect 功能支持的语言](supported-languages.md)。
  + 选择对选定的或所有敏感数据实体进行密文
  + 替换为通用占位符 ([PII]) 或实体特定的占位符 ([姓名]、[CREDIT\$1CARD])
+ 自定义消息处理器（通过 Lambda）。有关更多信息，请参阅[什么是 Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)？ 在 AWS *Lambda 开发者指南中。*
  + 整合第三方语言翻译服务
  + 应用亵渎内容过滤
  + 使用 AI/LLM 服务转换消息
  + 实施特定于业务的消息修改

要配置消息处理，请在**设置记录和分析行为**块中定义密文规则。有关更多信息，请参阅 [启用对敏感数据的加密](enable-analytics.md#enable-redaction)。您也可以指定 Lambda 函数进行自定义处理。

您的自定义处理器 Lambda 将采用以下格式的输入 JSON：

```
{
  "version": "1.0",
  "instanceId": "string",
  "associatedResourceArn": "string",
  "chatContent": {
    "absoluteTime": "string",
    "content": "string",
    "contentType": "string",
    "id": "string",
    "participantId": "string",
    "displayName": "string",
    "participantRole": "string",
    "initialContactId": "string",
    "contactId": "string"
  }
}
```

并按以下格式输出一个 JSON：

```
{
  "status": "string", // "PROCESSED"|"APPROVED"|"FAILED"|"REJECTED"
  "result": {
    "processedChatContent": {
      "content": "string",
      "contentType": "string" // "text/plain"|"text/markdown"|"application/json"
    }
  }
}
```

当向聊天参与者发布时，经过处理的聊天内容将取代原始消息。