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

# 在 Amazon Connect 中設定客戶的聊天體驗
<a name="enable-chat-in-app"></a>

您可以使用以下其中一種方法，為您的客戶提供聊天體驗：
+ [將聊天使用者介面新增至 Amazon Connect 託管的網站](add-chat-to-website.md). 
+ [使用 Amazon Connect 開放原始碼範例自訂聊天](download-chat-example.md). 
+ [使用 Amazon Connect API 自訂您的解決方案](integrate-with-startchatcontact-api.md)。在自訂您自己的聊天體驗時，我們建議您從 Amazon Connect ChatJS 開放原始碼程式庫開始。如需詳細資訊，請參閱 GitHub 上的 [Amazon Connect ChatJS](https://github.com/amazon-connect/amazon-connect-chatjs) 儲存庫。

## 更多自訂聊天體驗的資源
<a name="more-resource-customize-chat"></a>
+ 互動式訊息可為客戶提供提示且預先設定的顯示選項，供客戶選擇。這些訊息由 Amazon Lex 提供支援，並透過 Amazon Lex 使用 Lambda 進行設定。如需有關如何透過 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 串流](https://github.com/aws/amazon-connect-streams)。用於將您的現有應用程式與 Amazon Connect 整合。您可以將聯絡控制面板 (CCP) 元件嵌入到應用程式中。
+  [為採用 AI 技術的聊天啟用訊息串流](message-streaming-ai-chat.md) 

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

**重要**  
**嘗試聯絡 Amazon 尋求支援？** 請參閱 [Amazon 客戶服務](https://www.amazon.com/gp/help/customer/display.html?icmpid=docs_connect_messagingcap_customerservice) (Amazon 訂單和交付) 或 [AWS Support](https://aws.amazon.com/premiumsupport/?icmpid=docs_connect_messagingcap_premiumsupport) (Amazon Web Services)。

Amazon Connect 可讓您在網站和行動應用程式中建立聊天訊息功能，包括行動聊天、網路聊天、SMS 和第三方簡訊服務。它使您的客戶能夠從任何業務應用程式、Web 或行動裝置開始與客服中心的客服人員聊天。

互動是非同步的，可讓客戶與客服人員或 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 訊息。您可以使用 取得啟用 SMS 功能的電話號碼 AWS End User Messaging SMS，將其匯入 Amazon Connect，然後將其指派給流程。如需詳細資訊，請參閱：
  + [透過 請求啟用 SMS 的電話號碼 AWS End User Messaging SMS](sms-number.md)
  + [在 Amazon Connect 中設定 SMS 訊息](setup-sms-messaging.md)

然後，客服人員可以開始透過聯絡控制面板接受聊天。

您可以在用於呼叫/聊天/任務的相同報告體驗中，查看聊天訊息頻道的即時和歷史指標 (例如，到達時間和處理時間) 作為整體聊天頻道指標的一部分，以評估客服人員績效和生產力。

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_tw/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_tw/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 機器人詢問他們是否因同樣的問題或不同的問題與您聯絡。

您可以指定一個比聊天持續時間短得多的等待時間，以協助確保客戶擁有良好的體驗。否則，客戶可能會在 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 會託管小工具，因此可以確保最新版本始終存在於您的網站上。

**提示**  
通訊小工具的使用取決於預設 Service Quotas，例如每個訊息所需的字符數。將通訊小工具啟動到生產環境之前，請確定已針對組織的需求設定 Service Quotas。如需詳細資訊，請參閱[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 API 在您的應用程式中啟動聊天。](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` | String | 強制，自動產生 | N/A | 
| `styles` | String | 強制，自動產生 | N/A | 
| `supportedMessagingContentTypes` | 陣列 | 強制，自動產生 | N/A | 
| `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` | Number | 新開始聊天工作階段的總持續時間 | 預設值：1500 - 最少 60，最大：10080 | 
| `enableLogs` | Boolean | 啟用偵錯工具 | 預設：false | 
| `language` | String |  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` | Boolean | 停用從通訊小工具追蹤用戶端指標的功能。 | 預設：false | 
| `nonce` | String | 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_tw/connect/latest/adminguide/supported-snippet-fields.html) | 
| `initialMessage` | String | 要傳送至新建立聊天的訊息。長度限制：最小值為 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` | Boolean | 為 Lex Bot 訊息啟用模擬輸入指標。 | 預設：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 版本 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_tw/connect/latest/adminguide/images/chatwidget-customize-chat-window-button.png)

1. 在**通訊小工具**頁面上，選擇**新增通訊小工具**，開始自訂新的通訊小工具體驗。若要編輯、刪除或複製現有的通訊小工具，請從**動作**欄下方的選項中進行選擇，如下圖所示。  
![\[通訊小工具頁面，新增通訊視窗小工具按鈕連結。\]](http://docs.aws.amazon.com/zh_tw/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_tw/connect/latest/adminguide/images/comm-widget-page-chat.png)

1. 在**建立通訊小工具**頁面上，選擇小工具按鈕樣式，並顯示名稱和樣式。

   當您選擇這些選項時，小工具預覽會自動更新，讓您可以了解客戶的體驗。  
![\[通訊小工具的預覽。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/netra-chat-preview.png)

**按鈕樣式**

1. 輸入十六進位值 ([HTML 顏色代碼](https://htmlcolorcodes.com/))，以選擇按鈕背景的顏色。

1. 選擇**白色**或**黑色**作為圖示顏色。無法自訂圖示顏色。

**小工具標頭**

1. 提供標題訊息和顏色，以及小工具背景顏色的值。

1. **標誌 URL**：從 Amazon S3 儲存貯體或其他線上來源插入標誌橫幅的 URL。
**注意**  
如果自訂頁面中的通訊小工具預覽來自 Amazon S3 儲存貯體以外的線上來源，則不會顯示標誌。但是，當自訂通訊小工具實作到您的頁面時，將顯示標誌。

   橫幅必須是 .jpg 或 .png 格式。影像可以是 280 像素 (寬度) 乘 60 像素 (高度)。任何大於這些尺寸的影像都會縮放，以符合 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.  **Typeface**：請使用下拉式清單選擇通訊小工具的文字字型。

1. 
   + **系統訊息顯示名稱**：輸入新的顯示名稱以覆寫預設值。預設值是 **SYSTEM\$1MESSAGE**。
   + **機器人訊息顯示名稱**：輸入新的顯示名稱以覆寫預設值。預設值是 **BOT**。
   + **文字輸入預留位置**：鍵入新預留位置文字以覆寫預設值。預設值是 **輸入訊息**。
   + **結束聊天按鈕文字**：輸入新文字以取代預設值。預設值是 **結束聊天**。

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_tw/connect/latest/adminguide/images/chatwidget-add-domain.png)

   網域允許清單行為：
   + 自動包含子網域。例如，如果您允許 example.com，則也會允許其所有的子網域 (例如 sub.example.com)。
   + 通訊協定 http:// 或 https:// 必須完全符合您的組態。在設定允許的網域時，指定確切的通訊協定。
   + 自動允許所有 URL 路徑。例如，如果允許 example.com，則其下的所有頁面 (例如 example.com/cart 或 example.com/checkout) 都可供存取。您無法允許或封鎖特定子目錄。
**重要**  
仔細檢查您的網站 URL 是否有效而且沒有錯誤。請包含以 https://開頭的完整 URL。
我們建議您在生產環境網站和應用程式中使用 https://。

1. 在**為您的通訊小工具新增安全項**下，我們建議您選擇**是**，並與您的網站管理員合作，設定您的網路伺服器針對新的聊天請求發出 JSON Web Token (JWT)。這可讓您在啟動新聊天時提供更多控制權，包括確認傳送至 Amazon Connect 的聊天請求是否來自經過驗證的使用者。  
![\[為新的通訊小工具請求啟用安全性。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chatwidget-choose-security.png)

   選擇 **是** 會產生下列情況：
   + Amazon Connect 會在下一頁提供 44 個字元的安全金鑰，您可以用來建立 JSON 網路記號 (JWT)。
   + Amazon Connect 會在通訊小工具嵌入指令碼中新增回呼函數，該指令碼會在聊天啟動時檢查 JSON 網路記號 (JWT)。

     您必須在內嵌程式碼片段中實作回呼函數，如下列範例所示。

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

   如果您選擇此選項，則在下一步中，您將獲得在網站上發起的所有聊天請求的安全密鑰。請您的網站管理員設定您的網頁伺服器，使用此安全金鑰發出 JWT。

1. 選擇**儲存**。

## 步驟 3：確認並複製通訊小工具程式碼和安全密鑰
<a name="confirm-and-copy-chat-widget-script"></a>

在此步驟中，您將確認您的選擇，複製通訊小工具的程式碼，並將其嵌入您的網站中。如果您在[步驟 2](#chat-widget-domains) 中選擇使用 JWT，您也可以複製金鑰來建立它們。

### 安全金鑰
<a name="chat-widget-security-key"></a>

使用此 44 個字符的安全金鑰，從您的 Web 伺服器生成 JSON Web 權杖。如果您需要變更這些金鑰，也可以將其更新或輪換。當您執行此操作時，Amazon Connect 會為您提供新的金鑰，並保留先前的金鑰，直到您有機會更換為止。部署新金鑰後，您可以返回 Amazon Connect 並刪除先前的金鑰。

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


當您的客戶與您網站上的開始通訊圖示進行互動時，聊天小工具會請求您的網路伺服器以獲取 JWT。提供此 JWT 時，小工具會將其納入為最終客戶對 Amazon Connect 聊天請求的一部分。然後，Amazon Connect 使用該密鑰解密權杖。如果成功了，這將確認 JWT 是由您的網路伺服器發出的，而 Amazon Connect 會將聊天請求轉接到您的聯絡中心客服人員。

#### JSON Web 權杖詳細資訊
<a name="jwt"></a>
+ 演算法：**HS256**
+ 宣告：
  + **sub**：*widgetId*

    將 `widgetId` 取代為您自己的 widgetId。若要尋找您的 widgetId，請參閱範例 [通訊小工具文字記錄](#chat-widget-script)。
  + **iat**：\$1發行時間。
  + **exp**：\$1有效期限 (最多 10 分鐘)。
  + **segmentAttributes (選用)**：使用屬性對應存放在個別聯絡區段上的一組系統定義的鍵值對。如需詳細資訊，請參閱 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html#connect-StartChatContact-request-SegmentAttributes) API 中的 SegmentAttributes。
  + **屬性 (選用)**：具有字串對字串鍵值對的物件。聯絡屬性必須遵循 [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 如需有關日期格式的資訊，請參閱下列 Internet Engineering Task Force (IETF) 文件：[JSON Web Token (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_tw/connect/latest/adminguide/images/chatwidget-code.png)


當您的網站載入時，客戶會先看到**開始**圖示。當他們選擇此圖示時，通訊小工具將開啟，客戶可以向您的客服人員發送訊息。

若要隨時變更通訊小工具，請選擇**編輯**。

**注意**  
儲存的變更會在幾分鐘內更新客戶體驗。在保存之前確認您的小工具組態。

![\[他在視窗小工具預覽上編輯連接。\]](http://docs.aws.amazon.com/zh_tw/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`  | Boolean  | 一個標誌，用於啟用/禁用自動啟動小工具，而無需使用者按一下頁面加載。 | 未定義 | 
|  `alwaysHideWidgetButton`  | Boolean  | 用於啟用/禁用渲染小工具圖標按鈕的標誌 (除非有正在進行的聊天會話)。 | 未定義 | 
|  `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_tw/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) 向客服人員程式顯示該資訊，或在流程中的其他位置使用該資訊。

例如，您可以自訂流程，在歡迎訊息中說出客戶的名稱。或者，您可以使用業務特定的屬性，例如帳戶/成員 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) 物件對應。屬性是標準 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_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\$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_tw/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` 字串。圖示必須在公共 URL 上受管。

```
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_tw/connect/latest/adminguide/images/chat-customization-diagram2.png)


## 支援的選項和限制
<a name="customization-options-constraints"></a>

下表會列出支援的自訂欄位和建議的數值條件限制。


| 自訂配置選項 | Type | 描述 | 
| --- | --- | --- | 
|  `header.dropdown`  |  Boolean  |  呈現標頭下拉式功能表，而不是預設的頁腳  當您將此選項設定為 `true` 時，**文字記錄下載**按鈕會出現並可見，直到您將選項設定為 `false`，或直到您移除該選項為止。   | 
| `header.dynamicHeader` | Boolean | 將標頭標題動態設定為「與 Bot/AgentName 聊天」。 | 
| `header.hideTranscriptDownloadButton` | Boolean | 隱藏標頭下拉式功能表中的[下載文字記錄](chat-widget-download-transcript.md)按鈕。預設值為 false。 | 
|  `transcript.hideDisplayNames`  |  Boolean  |  隱藏所有顯示名稱，如果 `eventNames` 未提供，將套用預設名稱遮罩。  | 
|  `transcript.eventNames.customer`  |  String  |  遮蓋客戶的顯示名稱。  | 
|  `transcript.eventNames.agent`  |  String  |  遮蓋客服人員的顯示名稱。  | 
|  `transcript.eventNames.supervisor`  |  String  |  遮蓋主管的顯示名稱。  | 
|  ` transcript.eventMessages.participantJoined`  |  String  |  覆寫文字記錄中關於參與者加入聊天時的事件訊息。如果指定空白字串，則會在文字記錄中省略事件訊息。`{name}` 可以傳入訊息中，且將取代為對應參與者的顯示名稱。預設訊息為 `{name} has joined the chat`。  | 
|  `transcript.eventMessages.participantDisconnect`  |  String  |  覆寫文字記錄中關於參與者聊天連線中斷時的事件訊息。如果指定空白字串，則會在文字記錄中省略事件訊息。`{name}` 可以傳入訊息中，且將取代為對應參與者的顯示名稱。預設訊息為 \$1`name} has been idle too long, disconnecting`。  | 
|  `transcript.eventMessages.participantLeft`  |  String  |  覆寫文字記錄中關於參與者退出聊天時的事件訊息。如果指定空白字串，則會在文字記錄中省略事件訊息。`{name}` 可以傳入訊息中，且將取代為對應參與者的顯示名稱。預設訊息為 `{name} has left the chat`。  | 
|  `transcript.eventMessages.participantIdle`  |  String  |  覆寫文字記錄中關於參與者閒置時的事件訊息。如果指定空白字串，則會在文字記錄中省略事件訊息。`{name}` 可以傳入訊息中，且將取代為對應參與者的顯示名稱。預設訊息為 `{name} has become idle`。  | 
|  `transcript.eventMessages.participantReturned`  |  String  |  覆寫文字記錄中關於參與者返回聊天時的事件訊息。如果指定空白字串，則會在文字記錄中省略事件訊息。`{name} ` 可以傳入訊息中，且將取代為對應參與者的顯示名稱。預設訊息為 `{name} has returned`。  | 
|  `transcript.eventMessages.chatEnded`  |  String  |  覆寫文字記錄中關於聊天結束時的事件訊息。如果指定空白字串，則會在文字記錄中省略事件訊息。`{name}` 可以傳入訊息中，且將取代為對應參與者的顯示名稱。預設訊息為 `Chat has ended!`  | 
|  `transcript.displayIcons`  |  Boolean  |  啟用訊息顯示圖示。  | 
|  `transcript.iconSources.botMessage`  |  String  |  為機器人訊息顯示的圖示必須託管於公開 URL 上。  | 
|  `transcript.iconSources.systemMessage`  |  String  |  為系統訊息顯示的圖示必須託管於公開 URL 上。  | 
|  `transcript.iconSources.agentMessage`  |  String  |  為客服人員訊息顯示的圖示必須託管於公開 URL 上。  | 
|  `transcript.iconSources.customerMessage`  |  String  |  為客戶訊息顯示的圖示必須託管於公開 URL 上。  | 
|  `composer.alwaysHideToolbar`  |  Boolean  |  隱藏包含文字樣式功能的格式工具列，例如粗體、斜體，以及項目符號和編號清單選項。  | 
|  `composer.disableEmojiPicker`  |  Boolean  |  使用 [RTF 文字編輯器](enable-text-formatting-chat.md)時停用表情符號選擇器。  | 
| `composer.disableCustomerAttachments` | Boolean | 防止客戶傳送或上傳附件。 | 
| `composer.hide` | Boolean | 隱藏編譯器 (`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`  |  Boolean  |  隱藏**結束聊天**按鈕的預設頁腳。  | 
|  `footer.skipCloseChatButton`  |  Boolean  |  按一下**結束聊天**按鈕即可直接關閉小工具，而不顯示**關閉**按鈕。  | 
| `endChat.enableConfirmationDialog` | Boolean | 啟用結束聊天確認對話方塊。若未提供 confirmationDialogText，則使用預設文字。 | 
| `endChat.confirmationDialogText.title` | String | 覆寫結束聊天確認對話方塊的標題。 | 
| `endChat.confirmationDialogText.message` | String | 覆寫結束聊天確認對話方塊的訊息。 | 
| `endChat.confirmationDialogText.confirmButtonText` | String | 覆寫結束聊天確認對話方塊中的確認按鈕文字。 | 
| `endChat.confirmationDialogText.cancelButtonText` | String | 覆寫結束聊天確認對話方塊中的取消按鈕文字。 | 
| `attachment.rejectedErrorMessage` | String | 覆寫聊天小工具附件拒絕的錯誤訊息。 | 

# 在 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_tw/connect/latest/adminguide/images/chat-widget-download-transcript-pdf-1.png)


選擇**下載聊天文字記錄**，就會啟動 PDF 下載。聊天文字記錄的 PDF 會顯示所有訊息、顯示名稱、時間戳記和訊息事件，例如參與者離開或加入。

![\[下載聊天文字記錄範例。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chat-widget-download-transcript-pdf-2.png)


# 使用 Amazon Connect 開放原始碼範例自訂聊天
<a name="download-chat-example"></a>

您可以進一步自訂客戶用來與客服人員互動的聊天體驗。使用 GitHub 上的 [Amazon Connect 開放原始碼程式庫](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/cloudformationTemplates/asyncCustomerChatUX)。這是協助您快速入門的平台。以下是其運作方式：
+ GitHub 儲存庫連結至 CloudFormation 範本，該範本會啟動 Amazon API Gateway 端點，該端點則會啟動一個 Lambda 函數。您可以使用此範本作為一個範例。
+ 建立 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 API 在您的應用程式中啟動聊天。
<a name="integrate-with-startchatcontact-api"></a>

使用 Amazon Connect API 中的 StartChatContact API 在您自己的應用程式中啟動聊天。

若要啟動聊天，請使用 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API。

第一次開始探索聊天體驗時，您會注意到聊天並未計入歷史指標報告中的 **接通的聯絡案例** 指標。這是因為在聯絡人記錄中，聊天的啟動方法是 **API**。

下圖的聯絡人記錄顯示*初始化方法*設定為 *API*。

![\[聯絡人記錄，啟動方法設定為 API。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/ctr-api.png)


將聊天轉接給客服人員後，**來電的聯絡**指標會遞增。轉接的聯絡人記錄不會再遞增 API，但它會將 **接通的聯絡案例** 遞增。

# 在聊天訊息送達時傳送瀏覽器通知給客戶
<a name="browser-notifications-chat"></a>

通訊小工具支援透過桌面裝置為您的客戶提供瀏覽器通知。具體來說，當您的客戶收到新訊息，但他們在包含聊天視窗的網頁上沒有動靜，則會透過 Web 瀏覽器收到通知。當您的客戶按一下或點選此通知時，他們會自動重新導向至包含聊天視窗的網頁。您的客戶可以在每個聊天對話開始時啟用或停用通知。

下圖顯示了當客戶不在包含聊天視窗的網頁上時收到的通知橫幅範例。橫幅告訴您的客戶他們有新的訊息，並顯示網站的名稱。

![\[一個 Google Chrome 橫幅，說明您已收到新訊息。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chatwidget-notification-banner.png)


客戶還會在通訊小工具最小化時收到紅點通知圖示。下圖顯示客戶在聊天視窗最小化時收到的通知圖示影像。

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


這兩個功能都會自動包含在通訊小工具中。您無需執行任何步驟即可將其提供給客戶。

當您的客戶啟動聊天，但尚未允許來自您網站或網域的通知時，會收到快顯視窗，以允許/拒絕通知。授予通知許可後，當客服人員不在具有聊天視窗的網頁上時，就會開始收到瀏覽器通知 (關於客服人員傳送的任何訊息或附件)。即使您已經實作了通訊小工具，此行為也適用。

## 如何測試
<a name="test-browser-notifications-chat"></a>

1. 當您以測試客戶身分允許通知，且客服人員已連線至聊天室，請將聊天視窗最小化，然後開啟新的瀏覽器實例，這樣您就不會出現在包含聊天視窗的網頁上。

1. 從客服人員視窗傳送訊息。

1. 身為測試客戶，您會看到通知橫幅。

1. 選擇或輕觸通知橫幅。您將自動前往包含聊天視窗的網頁。

1. 由於您之前將通訊視窗最小化，您也會在聊天小工具上看到通知圖示 (紅點)。

如果您無法看到瀏覽器通知，請檢查下列各項：
+ 您正在使用[支援的瀏覽器](add-chat-to-website.md#chat-widget-supported-browsers)。
+ 在有聊天視窗網頁的瀏覽器上允許/啟用通知許可。
+ 當您所在的網頁與包含聊天視窗的網頁不同時，客服人員 (或在您的客服人員聊天工作階段中的您) 發送了新的訊息/附件。要讓小工具上的通知圖示 (紅點) 可見，請將聊天視窗縮到最小。
+ 來自瀏覽器的通知不會暫停 (暫時關閉)。

# 以程式設計方式中斷 Amazon Connect 通訊小工具的聊天工作階段
<a name="programmatic-chat-disconnect"></a>

您可以呼叫存放在小工具 `iframe` 的 `disconnect` 方法，以程式設計方式使用 JavaScript 中斷通訊小工具的聊天工作階段連線。從小工具的託管文件中，您可以使用下列程式碼片段來參考 `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` 是更新式的頁面生命週期事件，所有主要瀏覽器和作業系統均加以支援。`beforeunload` 是替代事件，可在 `pagehide` 事件無法一致呼叫中斷連線時試著使用。`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>

另一個使用案例是在使用者切換內容時觸發中斷連線，例如，當使用者切換或最小化索引標籤/應用程式，或鎖定其畫面時。`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>

若要傳遞自訂樣式，請使用下列範例程式碼區塊，並將其嵌入 Widget。 會自動 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` 樣式存在於全域且存在於文字記錄元件中。元件層級樣式優先順序更高，並將在聊天小工具上顯示。


|  自訂樣式名稱  |  Description  |  建議限制  | 
| --- | --- | --- | 
|  `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 位置。例如，AmazonEmber Light Typeface 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_tw/connect/latest/adminguide/images/chatwidget-elements.png)


## 如何覆寫通訊小工具的系統與機器人顯示名稱和標誌
<a name="pass-override-system"></a>

若要覆寫 Amazon Connect 管理員網站中設定的系統/機器人顯示名稱和標誌組態，請將下列程式碼區塊嵌入小工具程式碼片段。下列範例中顯示的所有欄位均為選填。

```
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>


| 自訂樣式名稱 | Description | 建議限制 | 
| --- | --- | --- | 
|  `header.headerMessage`  | 標頭訊息的文字 | 長度下限：1 個字元 長度上限：11 個字元  建議根據標頭寬度進行調整 | 
|  `header.logoUrl`  | 指向標誌影像的 URL |  長度上限：2048 個字元 必須是指向 .png、.jpg 或 .svg 檔案的有效 URL | 
|  `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`。
+ **問題：**結束聊天按鈕位於頁尾區域之外。

  **修復：**使用較小的 `buttonFontSize` 或較大的 `footerHeight`。

# 使用 CSS/JavaScript 將 Amazon Connect 小工具按鈕和框架設為目標
<a name="target-widget-button"></a>

通訊小工具會直接在託管網站上呈現開啟/關閉小工具按鈕和小工具框架。您可以使用特定選取器，使用 CSS 將這些元素設為目標，或在 JavaScript 中加以參考。

**提示**  
若要更新小工具按鈕的顏色，或小工具本身的樣式，請使用 [Amazon Connect 管理員網站](add-chat-to-website.md#customize-chat-widget)。如需更多可自訂的樣式，您可以直接將[自訂樣式傳遞](pass-custom-styles.md)至通訊小工具。

## 小工具元素 ID 和範例
<a name="widget-elementid"></a>

下圖顯示聊天小工具按鈕在使用者畫面上的顯示情形。第一個影像顯示用來開啟聊天小工具的 [開啟] 按鈕。第二個影像顯示用來關閉聊天小工具的 [關閉] 按鈕。

![\[開啟和關閉聊天視窗的聊天小工具並排影像。\]](http://docs.aws.amazon.com/zh_tw/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_tw/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_tw/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>

在聊天工作階段期間，使用聊天應用程式的客戶失去其網路/WebSocket 連線。他們很快就重新取得連線，但客服人員在這段期間傳送的訊息未呈現在客戶的聊天介面中。

下圖顯示客戶的聊天介面和客服人員的聯絡人控制台並排的範例。客服人員傳送的訊息未呈現在客戶的聊天工作階段中。但在客服人員看來，客戶已收到訊息。

![\[CCP 中未傳送給聯絡人的訊息。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/tw-cw-001-message-not-sent.png)


如果客戶的聊天應用程式失去其網路/WebSocket 連線，則聊天使用者介面必須執行下列動作，才能擷取未來的訊息，以及在連線中斷期間傳送給客戶的訊息：
+ 重新建立 WebSocket 連線，以接收未來傳入的訊息。
+ 提出 [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。`chatSession.onConnectionEstablished` 事件處理常式會在 WebSocket 重新連線時觸發。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 中的 UI 建置器以取得逐步指南中的資源 step-by-step](no-code-ui-builder.md)。

連線動作按鈕可讓您從表單中擷取使用者輸入，然後選取提交表單時所要採取的動作 - 啟動任務/電子郵件或聊天。

# 啟用聊天後問卷
<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 Communication Widget：

1. 開啟 Amazon Connect 主控台並導覽至**通訊小工具**。

1. 透過通訊小工具頁面啟用聊天後問卷設定。  
![\[顯示聊天後問卷選項的通訊小工具設定頁面。\]](http://docs.aws.amazon.com/zh_tw/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)。

有兩種方式可在中斷連線流程中實作問卷：
+ **選項 1：使用 ShowView 區塊** - 使用 [Amazon Connect 中的流程區塊：顯示檢視](show-view-block.md)顯示自訂問卷界面。
+ **選項 2：使用 Lex** - 與 Amazon Lex 整合以收集文字型問卷。如需詳細資訊，請參閱[將 Amazon Lex 機器人新增到 Amazon Connect](amazon-lex.md)。

**注意**  
對於主管插斷提示案例，請確保在**轉接至佇列**之前新增[Amazon Connect 中的流程區塊：設定工作佇列](set-working-queue.md)區塊。省略它會導致聊天聯絡人終止，而不是傳輸此功能。  

![\[顯示為主管插斷案例轉接至佇列之前設定工作佇列區塊的流程圖。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/post-chat-survey-set-working-queue-block.png)


**聯絡追蹤記錄**  
當客戶結束聊天工作階段時，Amazon Connect 會在 `CUSTOMER_DISCONNECT`中`disconnectReason`將 設定為 [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_tw/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 搭配 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 Chat 整合到您的行動應用程式中。您可以使用下列其中一個選項：
+ [WebView 整合](#webview)
+ [適用於 iOS 和 Android 的Amazon Connect Chat SDK](#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 和 iOS 分別使用 `WebView` 與 `WKWebView`，以提供順暢且全面的聊天介面。團隊若想要以快速、立即可用的解決方案來整合聊天功能，而無需大量自訂，就非常適用此方法。

此方法可確保安全通訊，並且使用 Web 型 Amazon Connect 聊天介面。不過，您必須設定應用程式以正確處理 Cookie 和 JavaScript。

如需實作 WebView 整合的詳細資訊，請參閱 Amazon Connect 聊天 [UI 範例](https://github.com/amazon-connect/amazon-connect-chat-ui-examples/tree/master/mobileChatExamples) GitHub 儲存庫。

**建議**：若要快速開發並盡可能減輕維護工作，同時確保全面的聊天功能，WebView 型整合非常適用。

### Amazon Connect 適用於 Mobile SDKs
<a name="integrate-chat-with-mobile-sdks-for-mobile"></a>

適用於 iOS 和 Android 的 Amazon Connect 聊天開發套件可簡化原生行動應用程式的 Amazon Connect 聊天整合。 SDKs 這類 SDK 有助於處理用戶端聊天邏輯，以及類似於 Amazon Connect ChatJS Library 的後端通訊。

 Amazon Connect 聊天SDKs包裝 Amazon Connect 參與者服務 APIs，並抽象化聊天工作階段和 WebSocket 的管理。這可讓您專注於使用者介面和體驗，同時依賴 Amazon Connect 聊天開發套件與所有後端服務互動。此方法仍要求您使用自己的聊天後端來呼叫 `StartChatContact` API Amazon Connect 以啟動聯絡。
+ 如需 Swift 型 iOS SDK 的詳細資訊，請參閱[適用於 iOS 的Amazon Connect Chat SDK](https://github.com/amazon-connect/amazon-connect-chat-ios) GitHub 頁面。
+ 如需 Kotlin 型 Android SDK 的詳細資訊，請參閱[適用於 Android 的Amazon Connect Chat SDK](https://github.com/amazon-connect/amazon-connect-chat-android) GitHub 頁面。

**優點**：原生 SDK 可實現強大的功能和高效能，因此非常適用於需要深度自訂和順暢使用者體驗的應用程式。

### React Native 整合
<a name="react-native-integration"></a>

Amazon Connect Chat React Native 整合提供了跨平台解決方案。它可讓團隊使用共用的程式碼庫為 Android 和 iOS 建置聊天功能。此方法可兼顧自訂和開發效率，同時利用 React Native 的功能來建立強大的行動應用程式。

此整合使用原生橋接器來存取進階功能，並確保在各平台間能夠有一致的效能和使用者體驗。使用 `react-native-websocket` 之類的程式庫與 `axios` 的 API 呼叫，可更輕鬆地實作 WebSocket 通訊等重要功能。

**最適用於**：想要盡可能重複使用程式碼，同時保有功能彈性的團隊。

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

下圖顯示使用行動應用程式的客戶與客服人員之間的程式設計流程。圖表中的編號文字對應至影像下方的編號文字。

![\[顯示 Amazon Connect 聊天程式流程的圖表。\]](http://docs.aws.amazon.com/zh_tw/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 傳送請求至 。此作業需要特定參數，例如[執行個體](amazon-connect-instances.md)的 API 端點和 ID 與[聯絡](connect-contact-flows.md)流程，以驗證和起始聊天。

1. `StartChatContact` API 與您的後端系統互動，以取得參與者權杖和聯絡人 ID，作為聊天工作階段的唯一識別碼。

1. 應用程式 UI 將 `StartChatContact` 回應傳遞至行動 SDK，使 SDK 能夠與 [Amazon Connect 參與者服務](https://docs.aws.amazon.com/connect/latest/APIReference/API_Operations_Amazon_Connect_Participant_Service.html)正確通訊，並設定客戶的聊天工作階段。

1. SDK 向 UI 公開 [chatSession](https://github.com/amazon-connect/amazon-connect-chat-ios?tab=readme-ov-file#chatsession-apis) 物件，其中包含與聊天工作階段互動的易用方法。

1. 在幕後，SDK 會使用 [AWS SDK](https://aws.amazon.com/developer/tools/) 與 [Amazon Connect 參與者服務](https://docs.aws.amazon.com/connect/latest/APIReference/API_Operations_Amazon_Connect_Participant_Service.html)互動。與 Amazon Connect 參與者服務的通訊會負責處理所有客戶與聊天工作階段的互動。其中包括 `CreateParticipantConnection`、`SendMessage`、`GetTranscript` 或 `DisconnectParticipant` 等動作。

1. SDK 也會管理接收客服人員的訊息、事件和附件所需的 WebSocket 連線。這全都會由 SDK 處理和剖析，並以易於使用的結構呈現至 UI。

## 開始使用 Amazon Connect 聊天整合
<a name="integrate-chat-with-mobile-getting-started"></a>

下列步驟和資源將協助您開始將 Amazon Connect 聊天整合到原生行動應用程式：

1. 您可以查看我們在 GitHub 上的 [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) 堆疊，提供呼叫 StartChatContact 所需的後端。

1. 如需相關範例示範如何建置由 Amazon Connect Chat SDK 提供支援的行動聊天 UI，請參閱我們的 [UI 範例](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 聊天開發套件為聊天應用程式提供動力。

1. 查看[適用於 iOS 的Amazon Connect Chat SDK](https://github.com/amazon-connect/amazon-connect-chat-ios) 和[適用於 Android 的Amazon Connect Chat 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 Chat SDK 有任何疑問或問題，您可以在[適用於 iOS 的Amazon Connect Chat SDK 問題](https://github.com/amazon-connect/amazon-connect-chat-ios/issues)頁面或[適用於 Android 的Amazon Connect Chat SDK 問題](https://github.com/amazon-connect/amazon-connect-chat-android/issues)頁面上提出問題。如果行動聊天 UI 範例有問題，您可以在 [Amazon Connect 聊天 UI 範例問題](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)時，即可啟用現成的 RTF 格式設定。不需任何其他設定。

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) 之上您自己的 UI 解決方案)，請依照下列步驟執行：

   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 API 傳送 Markdown 文字的資訊：[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)，則可修改現有的邏輯，當您要傳送 Markdown 訊息時呼叫 [SendMessage](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendMessage.html)，並將 `text/markdown` (而非 `text/plain`) 作為 `contentType`。請務必更新 `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>

下列範例說明如何將可點選和可呼叫的連結新增至您的 Web 和行動應用程式。

```
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>

啟用聊天訊息的 Markdown 時，您可以對下列類型的聊天機器人訊息使用 RTF 格式：
+ [播放提示](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_tw/connect/latest/adminguide/images/chat-rtf-play-prompt-flow-1.png)


下圖顯示如何在[取得客戶輸入](get-customer-input.md)流程區塊中手動啟用提示，然後將流程區塊與 Amazon Lex 機器人建立關聯：

![\[此圖顯示一個流程區塊、一個提示與 2 個連結，一個用於常見問答集，另一個用於電話號碼。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chat-rtf-get-customer-flow.png)


下圖顯示以 SYSTEM\$1MESSAGE 和各種 BOT 訊息類型顯示提示的情形：

![\[此圖顯示 SYSTEM 和 BOT 訊息中的「檢閱我們的常見問答集」和「打電話給我們」連結。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chat-rtf-sys-bot-messages.png)


下圖顯示如何在 Amazon Lex 機器人意圖中設定提示：

![\[此圖顯示 Amazon Lex 意圖，其中包含一個提示與 2 個連結，一個用於常見問答集，另一個用於電話號碼。\]](http://docs.aws.amazon.com/zh_tw/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://*執行個體名稱*.my.connect.aws/。選擇**自訂通訊小工具**。  
![\[組態指南頁面，自訂通訊小工具選項。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chatwidget-customize-chat-window-button.png)

1. 選擇**編輯**。  
![\[已儲存的通訊小工具自訂頁面，「編輯」按鈕。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chatwidget-edit-messagereceipt.png)

1. **訊息回條** 預設並未啟用。設定為 **已啟用**。  
![\[訊息回條選項，已啟用。\]](http://docs.aws.amazon.com/zh_tw/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_tw/connect/latest/adminguide/setup-chat-timeouts.html)

**以分鐘為單位指定所有計時器。**
+ 最小：2 分鐘
+ 最長 480 分鐘 (8 小時)

**計時器適用於參與者角色，並適用於聊天的存在期間。**
+ 您可以為參與者角色 (例如客服人員和客戶) 設定計時器，而不是個別參與者。
+  設定計時器後，它們將適用於聊天的存在期間。如果聊天被轉接，計時器適用於新的客服人員/客戶互動。

## 聊天計時器的工作方式
<a name="how-chat-timer-work"></a>

計時器的行為如下：
+ 在客服人員和客戶都連線至聊天時，或客戶和自訂參與者 (例如自訂機器人) 連線時，計時器都會執行。
+ 計時器會在客服人員/自訂參與者加入聊天時首次啟動，並在客服人員/自訂參與者退出聊天時停止。
+ 如果兩者均已針對角色而設定，閒置計時器會在自動中斷連線計時器之前運行。例如，如果同時設定了兩個計時器，則只有在參與者視為閒置之後，才會啟動自動中斷連線計時器。
+ 如果角色只設定了一種類型的計時器，則該計時器會立即啟動。
+ 如果參與者在任何時刻傳送訊息，則會重設該參與者的計時器。若先前已被視為閒置，就不會再被視為閒置。
+ 附件新增至訊息時，聊天計時器會重設。
+  只要客服人員/自訂參與者留在聊天中，客服人員/自訂參與者加入時所設定的組態即適用。如果您在客服人員/自訂參與者和客戶已互相連線時更新計時器組態，則會儲存、但不套用新組態，除非有新的客服人員/自訂參與者連線至聊天。
+ 發生自動中斷連線事件時，除了客戶以外的所有參與者 (例如客服人員、任何監控主管或自訂參與者) 都會中斷連線。如果中斷連線的是客服人員，且 [設定中斷連線流程](set-disconnect-flow.md) 區塊已設定，聊天就會轉接至該處。

### 閒置計時器到期
<a name="idle-timer-expiry"></a>

以下是閒置計時器在客戶與自訂參與者互動期間到期時發生的情況：

1. 閒置事件會散發到所有 Websocket/串流端點。

1. 已設定的自動中斷連線計時器將會啟動。

1. 如果閒置計時器在聊天聯絡位於**等待**區塊時到期，則聯絡不會轉接至**時間已到期**分支。發生這種情況時，不會採取任何動作。

### 自動中斷自訂參與者連線
<a name="auto-disconnecting"></a>

當自動中斷連線計時器到期時，自訂參與者的聊天連線會中斷。

當自動中斷連線計時器到期時，Amazon Connect 會執行下列其中一個步驟：

1. 聊天目前位於為自訂參與者設定的 [等候](wait.md) 區塊中。
   + 自訂參與者的聊天連線會中斷，而聊天會取用**機器人參與者中斷連線**分支繼續流程。

1. 聊天目前位於為客戶設定的 [等候](wait.md) 區塊中，或聊天不在**等待**區塊中。
   + 自訂參與者的聊天連線中斷，不採取其他動作。

## 向參與者顯示的訊息
<a name="chat-timeouts-events"></a>

發生下列任一事件時，訊息會顯示給所有參與者：
+ 參與者已閒置。
+ 閒置的參與者傳送訊息，且不再處於閒置狀態。
+ 會發生自動中斷連線。因為客服人員被中斷連線，所以他們無法看到訊息。

這些事件不會保留在文字記錄中，也不會計費。

這些事件的預設訊息 (以所有支援的語言顯示) 會向聯絡人控制台 (CCP) 中的客服人員顯示。

下圖顯示客服人員在 CCP 中看到的預設閒置訊息範例。例如，*客服人員已閒置*。

![\[ccp，預設的閒置訊息。\]](http://docs.aws.amazon.com/zh_tw/connect/latest/adminguide/images/chat-timeout-message.png)


## 建議用法
<a name="chat-timeouts-usage"></a>

若要使用聊天逾時功能，建議您執行下列動作：

1. 在聯絡流程的 Lambda 中內嵌對 [UpdateParticipantRoleConfig](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateParticipantRoleConfig.html) 動作的呼叫。

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 終端使用者訊息](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-service.html)設定的。您可以在 iOS 或 Android 裝置上啟用行動聊天的推播通知，如此，即使客戶當下並未使用行動應用程式，您也能提醒他們有新訊息。您可以在與 [Amazon Connect 行動 SDK](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：從 Apple 的 APN 和 Google 的 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 推播通知服務 (APN) 登入資料，請參閱 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)。
+  Google Firebase Cloud Messaging (FCM) 登入資料可透過 Firebase 主控台取得，相關資訊請參閱 [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>

 您必須先[建立AWS 終端使用者訊息應用程式，並啟用推播通知](https://docs.aws.amazon.com/push-notifications/latest/userguide/procedure-enable-push.html)管道 (在 [AWS 主控台](https://console.aws.amazon.com/push-notifications/)中)，才能讓 Amazon Connect 傳送推播通知。

 請依照這些指示建立應用程式並啟用任何推播管道。若要完成此程序，只需輸入應用程式名稱即可。您可以稍後啟用或停用任何推播管道：

1.  在 https：//[https://console.aws.amazon.com/push-notifications/](https://console.aws.amazon.com/push-notifications/) 開啟 AWS 最終使用者傳訊推送主控台 

1.  選擇**建立應用程式**。

1.  針對**應用程式名稱**，輸入您的應用程式名稱。

1.  (選用) 依照這個選用步驟，啟用 **Apple 推播通知服務 (APN)**。

   1.  針對 **Apple 推播通知服務 (APN)**，選取**啟用**。

   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 與 `PINPOINT_APP` [IntegrationType](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html#API_CreateIntegrationAssociation_RequestSyntax)，將 AWS 最終使用者傳訊應用程式與[Amazon Connect 執行個體](https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html)建立關聯。您可以使用 [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開發套件取得裝置字符，並將其註冊至 Amazon Connect
<a name="step-4-enable-push-notifications-for-mobile-chat"></a>

您需要擷取裝置字符，並使用它向 Amazon Connect 聊天聯絡人註冊最終使用者行動裝置，以傳送聊天中新訊息的推播通知。 請閱讀下列 FCM/APNs開發人員文件，以了解裝置字符如何產生並從行動應用程式取得。
+  對於 Apple 的推播通知服務 (APN)，請參閱 Apple 開發人員文件中的[對 APN 註冊您的應用程式](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 函數，或是在聯絡轉接至佇列之前放置，如此，使用者只會在客服人員即將加入時接收到聯絡。進行 API 呼叫後，裝置就會開始在客服人員或系統傳入新訊息時接收推播通知。依預設會為所有的系統和客服人員訊息傳送推播通知。  
![\[在 Amazon Connect 管理員網站流程設計工具中調用 lambda 函數流程區塊。\]](http://docs.aws.amazon.com/zh_tw/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 聊天 UI 範例](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) 聊天 Webview 範例，示範如何整合 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)：參閱有關於[了解訊息傳遞](https://firebase.google.com/docs/cloud-messaging/understand-delivery?platform=android)的 FCM 文件，深入了解您的 FCM 用量。

   1.  Apple 推播通知服務 (APN)：檢閱有關於[使用指標和 APN 檢視推播通知狀態](https://developer.apple.com/documentation/usernotifications/viewing-the-status-of-push-notifications-using-metrics-and-apns)的 APN 文件章節，以監控您的通知狀態。

# 讓客戶能夠在 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"
   }
}
```

#### Configuration
<a name="usecase1-configuration"></a>
+ SourceContactId = 2222222-aaaa-bbbb-2222-222222222222222 (C2 的 contactId)
+ 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-2222-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"
   }
}
```

#### Configuration
<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-3333333333333 (C3) 作為「ContinuedFromContactId」。
+ 這個持續性聊天工作階段的 `RelatedContactId` 是 33333333-aaaa-bbbb-3333-3333333333333 (C3)

**注意**  
聊天連線為累積連線。聊天工作階段連結後，它們會繼續進行。  
例如，如果屬於過去聊天會話的聯絡人 (`contactId` C2) 連結到來自不同過去聊天會話的聯絡人 (`contactId` C1)，則通過鏈接 C2 建立的新持續性聊天工作階段也會導致 C1 的隱式鏈接。新的持續性聊天會話將具有以下鏈接：C3 → C2 → C1  
持續聊天工作階段從其繼續的過往 contactId 會顯示在 [StartChatContact](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartChatContact.html) API 回應的 `ContinuedFromContactId` 欄位中。它也位於該聯絡人之[聯絡人記錄](ctr-data-model.md#ctr-ContactTraceRecord)的 RelatedContactId 欄位中

## 如何存取持續性聊天的過去聊天聯絡人文字記錄
<a name="access-past-chat-transcript"></a>

存取持續性聊天的過去聊天記錄會使用現有的 `NextToken` 分頁模型。在新啟動的持續性聊天工作階段中，對 [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) 的初始呼叫會在回應中包含一個 `NextToken` (如果過去的聊天訊息存在)。`NextToken` 必須用於存取過去的聊天文字記錄，並在後續的 [GetTranscript](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_GetTranscript.html) 呼叫中，將 `ScanDirection` 設定為 `BACKWARD`，以擷取過去的聊天訊息。

如果過去有多個聊天訊息，[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 提供的 [API](https://docs.aws.amazon.com/connect/latest/APIReference/Welcome.html) 可讓您訂閱聊天訊息的即時串流。使用這些 API，您可以：
+ 建立新的聊天聯絡人時，即時串流聊天訊息。
+ 擴充目前的 Amazon Connect 聊天功能以支援使用案例，例如建置與 SMS 解決方案和第三方傳訊應用程式的整合、啟用行動推送通知，以及建立分析儀表板來監控和追蹤聊天訊息活動。

**注意**  
此頁面說明如何訂閱 SNS 端點，以在 Amazon Connect 中即時串流聊天訊息。如果您嘗試在 Amazon Connect 中啟用對話式 AI 互動的訊息串流，請參閱 [為採用 AI 技術的聊天啟用訊息串流](message-streaming-ai-chat.md)。

## 訊息串流 API 的運作方式
<a name="how-chat-message-streaming-apis-work"></a>

當 Amazon Connect Chat 聯絡人內發生某些事件時，會觸發 [Amazon Connect 訊息串流 API](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：建立標準 Amazon SNS 主題
<a name="step1-chat-streaming"></a>

1. 登入 Amazon SNS 主控台。

1. [在帳戶中建立 SNS 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html)。 AWS 在 **詳細資料** 區段中，選擇 **標準** 作為 **類型**，輸入主題的名稱，然後選擇 **建立主題**。
**注意**  
目前，訊息串流 API 僅支援使用標準 SNS 進行即時訊息串流。SNS 動作不支援 [Amazon SNS FIFO (先進先出) 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)。

1. 主題建立後，其 Amazon Resource Name (ARN) 會顯示於 **詳細資訊** 區段中。將主題 ARN 複製到剪貼簿。您將在下一個步驟和 [步驟 3：啟用聯絡人的訊息串流](#step3-chat-streaming) 中使用主題 ARN。

   此範例的輸出結果類似如下：

   ```
   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 以啟動聊天聯絡人。

   如需有關如何建立 SDK 用戶端以呼叫 Amazon Connect API 的資訊，請參閱下列主題：
   + [Class 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) 的 `ContactId` 和 `ParticipantToken` 回應，因為這些回應屬性會用於呼叫啟用串流所需的其他聊天 API。下個步驟會介紹這一點。

## 步驟 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 Resource Name (ARN) (請參閱 [步驟 1：建立標準 Amazon 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>
+ 使用傳遞為 true 的 `ConnectParticipant` 屬性呼叫 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)。
  + 您必須在建立聊天後的五分鐘內呼叫 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)。
  + 只有在 [步驟 2：啟動聊天聯絡人](#step2-chat-streaming) 中啟用了串流，且呼叫參與者為 `Customer` 時，才能在 `ConnectParticipant` 設定為 true 的情況下呼叫 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)。
  + 如果您已經使用 `WEBSOCKET` 成功連接到聊天聯絡人，則此步驟 (建立參與者連線) 是可選的。

## 後續步驟
<a name="nextsteps-chat-streaming"></a>

您已準備好使用訊息串流 API。

1. 若要確認是否正常運作，請檢查訊息是否已發布至您建立的 SNS 主題。您可以使用 Amazon CloudWatch 指標來執行此操作。如需指示，請參閱[使用 Amazon CloudWatch 監控 Amazon SNS 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-monitoring-using-cloudwatch.html)。

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。如果聊天或佇列對佇列聯絡流程中有新的客服人員，則 `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：建立標準 Amazon SNS 主題](chat-message-streaming.md#step1-chat-streaming) 中的資訊：
+ 請確認您使用的是標準 SNS，而不是 [Amazon SNS FIFO (先進先出)](https://docs.aws.amazon.com/sns/latest/dg/sns-fifo-topics.html)。目前，訊息串流 API 僅支援使用標準 SNS 進行即時訊息串流。
+ 確認您的帳戶中已正確套用 SNS 資源型許可。
  + 如果啟用了伺服器端加密，您需要授予相同的 Amazon Connect 服務主體許可，以便加密和解密。

## 流程無法啟動
<a name="contact-flow-not-starting"></a>

如果您使用訊息串流 API 來取代 Websocket，請傳送連線確認事件；請參閱 [步驟 4：建立參與者連線](chat-message-streaming.md#step4-chat-streaming)。這與連線到 Websocket 同義。流程只會在連線確認事件之後開始。

在 [StartContactStreaming](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartContactStreaming.html) 之後呼叫 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.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 聊天整合，以建立自訂的聊天流程體驗。

以下是如何自定義聊天流程體驗的概觀。聊天對話開始後，針對每個聊天區段實作這些步驟。我們建議您新增 [AWS Lambda 函數](invoke-lambda-function-block.md) 區塊，以便在聊天流程中呼叫 API。

**重要**  
在 [AWS Lambda 函數](invoke-lambda-function-block.md) 區塊前加入 [播放提示](play.md) 區塊。只有在**調用 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. 如需有關如何建立 SDK 用戶端以呼叫 Amazon Connect API 的資訊，請參閱下列主題：
      + [Class 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. 保留從 [CreateParticipant](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateParticipant.html) 獲得的 `ParticipantToken` 以呼叫。[CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html)。`CreateParticipantConnection` 會傳回一個 `ConnectionToken`，您可以用來呼叫其他 Amazon Connect Participant API。

      呼叫 [CreateParticipantConnection](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_CreateParticipantConnection.html) 來建立自訂參與者的連線時：
      + 將 `ConnectParticipant` 設定為 `True`，把自訂參與者標記為已連線以進行訊息串流。
      + 傳遞 `Type` 作為 `CONNECTION_CREDENTIALS`，以呼叫後續的 Amazon Connect Participant Service API。
      + `CreateParticipantConnection` 應在呼叫 `CreateParticipant` 後 15 秒內呼叫。

1. 將參與者新增至連絡人後，他們可以使用 Amazon Connect Participant Service API 與客戶交換訊息。

1. 若要中斷與會者的連線，請呼叫 [DisconnectParticipant](https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_DisconnectParticipant.html) API。

**注意**  
如果聯絡案例中已有客服人員或 Amazon Lex 機器人，則無法將自訂參與者新增至聊天中。
當客服人員或 Amazon Lex 機器人加入聯絡人時，自訂參與者將中斷連線。
一個連絡案例中只能有一個自訂參與者。
自訂參與者不允許存取客戶可能上傳的附件。

我們建議您設定自訂參與者可與連絡人聊天的時間長度：
+ 針對 `ParticipantRole` = `CUSTOM_BOT` 設定 [等候](wait.md) 區塊的 **逾時** 屬性。
+ 如果自訂機器人參與者在逾時之前未中斷連線，則會將連絡人轉接到 **時間已到期** 分支。這可讓您決定接下來要執行哪個區塊以解決客戶的查詢。

**注意**  
如果連絡人向下轉接到 **時間已到期** 分支，並不會中斷他們與連絡人的連線。您必須呼叫 [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.md) 區塊的運作情形。

在聊天聯絡進入**等待**區塊時啟動的**等待**區塊計時器會繼續運作。**等待**區塊計時器到期時，無論是否有任何閒置參與者計時器處於作用中狀態，聯絡都會繼續其流程，並轉接至**時間已到期**分支。

## 對秘訣進行故障診斷
<a name="ts-chat-custom-bot"></a>
+ `ResourceNotFoundException`: 

  如果您在呼叫 `CreateParticipantConnection` API 時為自訂參與者取得一個 `ResourceNotFoundException`，請檢查 `CreateParticipantConnection` API 是否在 `CreateParticipant` API 的 15 秒內呼叫。
+ `AccessDeniedException`: 

  如果您收到 `AccessDeniedException` 錯誤，且參與者角色是 CUSTOM\$1BOT，表示機器人正在嘗試存取附件。CUSTOM\$1BOT 的參與者角色不允許存取客戶上傳的附件。

# 在 Amazon Connect 中為聊天聯絡設定客戶身分驗證
<a name="customer-auth"></a>

您可以提示客戶在聊天期間登入和驗證。例如，系統會提示與聊天機器人互動的未驗證客戶在轉接至客服人員之前登入。

此內建功能會利用 Amazon Connect Customer Profiles 和 [Amazon Cognito](https://aws.amazon.com/cognito/)。如果您在設定期間選擇預設設定，則使用 Amazon Connect 執行個體中[已啟用](enable-customer-profiles.md)的客戶設定檔無需額外費用。如需 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. 在 [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/) 開啟 Amazon Connect 主控台。

1. 在執行個體頁面上，選擇執行個體別名。執行個體別名也是您的**執行個體名稱**，它會出現在您的 Amazon Connect URL 中。下圖顯示 **Amazon Connect 虛擬聯絡中心執行個體**頁面，其中包含執行個體別名周圍的方塊。  
![\[Amazon Connect 虛擬聯絡中心執行個體頁面，即執行個體別名。\]](http://docs.aws.amazon.com/zh_tw/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 開發人員指南》**中的[使用應用程式用戶端的特定應用程式設定](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。這是您的客戶在登入後自動導向的位置。在此頁面上，您可以檢查 URL 參數，如果有程式碼和狀態，您可以使用這些值呼叫 [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 Connect StartChatContact 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 支援聊天互動的訊息串流。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. 在導覽窗格中，選擇**流程** > **Amazon Lex 機器人**。

1. 在 **Lex 機器人組態**下，選取在 **Amazon Connect 中啟用訊息串流**。

**注意**  
當您使用主控台啟用訊息串流時，所需的`lex:RecognizeMessageAsync`許可會自動新增至機器人別名資源型政策。使用 API 時，您必須手動新增此許可。

![\[在 Amazon Connect 主控台中啟用訊息串流選項。\]](http://docs.aws.amazon.com/zh_tw/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 機器人別名的資源型政策。 Amazon Connect 

### 何時更新機器人的資源型政策
<a name="message-streaming-when-to-update"></a>
+ **新執行個體** – 根據預設，任何新關聯的 Amazon Lex 機器人別名都會在其別名政策`lex:RecognizeMessageAsync`中具有 。
+ **具有現有機器人的現有執行個體** – 如果執行個體先前使用 Amazon Lex 且您現在啟用訊息串流，您必須更新所有相關聯 Amazon Lex 機器人別名上的資源型政策，以包含新的許可。

### Lex 機器人別名資源型政策的範例程式碼片段
<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】) 或實體特定的預留位置 (【NAME】、【CREDIT\$1CARD】) 取代
+ 自訂訊息處理器 （透過 Lambda)。如需詳細資訊，請參閱 [Lambda 開發人員指南中的什麼是](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) *Lambda*？。 AWS 
  + 整合第三方服務以進行語言翻譯
  + 套用褻瀆篩選
  + 使用 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"
    }
  }
}
```

已處理的聊天內容會在發佈至聊天參與者時取代原始訊息。