本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在聊天啟動時，在聯絡人控制台 (CCP) 中將聯絡屬性傳遞至客服人員
<a name="pass-contact-attributes-chat"></a>

您可以使用[聯絡人屬性](what-is-a-contact-attribute.md)來擷取有關使用通訊小工具的聯絡人的資訊。然後，您可以透過聯絡控制面板 (CCP) 向客服人員程式顯示該資訊，或在流程中的其他位置使用該資訊。

例如，您可以自訂流程，在歡迎訊息中說出客戶的名稱。或者，您可以使用業務特定的屬性，例如帳戶/成員 ID、客戶識別符 (例如姓名和電子郵件)，或與聯絡人關聯的其他中繼資料。

## 如何將聯絡人屬性傳遞到通訊小工具
<a name="how-to-contact-attributes-chatwidget"></a>

1. 在通訊小工具中啟用安全性，如 [將聊天使用者介面新增至 Amazon Connect 託管的網站](add-chat-to-website.md) 中所述 (如果您尚未這麼做)：

   1. 在步驟 2 的 **為您的聊天小工具新增安全項** 下，選擇 **是**。

   1. 在步驟 3 中，使用安全金鑰產生 JSON 網頁權杖。

1. 將聯絡人屬性新增到 JWT 的有效負載作為 `attributes` 聲明。

   下面是你如何使用 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` (照原樣，全部為小寫)，並將物件作為其值。該物件必須具有字串對字串的鍵值對物件。如果在任何一個屬性中傳遞字串以外的任何內容，聊天將無法啟動。

   聯絡屬性必須遵循 [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) 物件對應。屬性是標準 Connect Customer 屬性。可從流程中加以存取。聯絡屬性必須遵循 [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_tw/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\_token 應該傳遞給 `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_tw/connect/latest/adminguide/images/test-chat-contact-attributes.png)