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

# 在聊天开始时，在联系人控制面板 (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)