> For the complete documentation index, see [llms.txt](https://library.zoom.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://library.zoom.com/technical-library/zh-tw/shang-wu-fu-wu/zoom-contact-center/expert-insights/integrate-engagement-data.md).

# 整合互動資料

### 概覽

Zoom 聯絡中心會在每次客戶互動期間產生有價值的互動資料，包括通話錄音、逐字稿、代理人備註和處置結果。請繼續閱讀，了解如何將互動資料儲存在外部系統中（例如 CRM 和其他記錄系統），以建立統一的客戶視圖、支援有效的代理人培訓，或在使用 Zoom 聯絡中心時滿足合規要求。

我們將拆解不同的整合方法，協助你根據代理人如何以更高效率工作來選擇最佳做法。

最佳方法主要取決於一個關鍵因素： **代理人處理互動的應用程式**。我們將討論的兩個選項是：

1. 代理人在 CRM 內使用現成的 ZCC CRM CTI 連接器。
2. 代理人在 Zoom Workplace 應用程式中工作，這需要使用 ZCC API 和 Webhooks 的自訂解決方案。

***

### 現成的 CRM CTI 連接器整合

這是最直接的方法。如果你的代理人正在使用 ZCC CRM CTI 連接器，大多數互動資料都可以在 Zoom 平台與適當的 CRM 之間自動同步。

#### <mark style="color:藍色;">運作方式</mark>

CTI 連接器會將 ZCC 代理人介面直接嵌入 CRM 中。當一段互動結束時，錄音、逐字稿、備註和處置結果等資料會自動儲存在 Zoom 中，並連結到 CRM 內相關的記錄（例如案件單或聯絡人）。

#### <mark style="color:藍色;">設定需求</mark>

可讓 Zoom 與 CRM 之間同步資料的功能屬於「現成提供」，但需要在 ZCC 管理入口網站中啟用。

請完成以下步驟：

{% stepper %}
{% step %}
**在 ZCC 管理入口網站中啟用**

以管理員身分登入 Zoom 管理入口網站，並前往 聯絡中心管理 > 整合 > 應用程式。

找到相關的 CRM 整合，並啟用適當設定，以允許將資料儲存在你的 CRM 中。
{% endstep %}

{% step %}
**CRM 權限**

請檢閱並遵循 [CRM 整合設定指南](https://support.zoom.com/) ，以確認你的 CRM 整合使用者具備所有相關物件所需的寫入權限。
{% endstep %}
{% endstepper %}

#### <mark style="color:藍色;">支援的 CRM 平台</mark>

當代理人使用下列 CRM 時，可透過 ZCC CRM CTI 連接器存取此功能：

* Salesforce
* Zendesk
* ServiceNow
* Microsoft Dynamics
* HubSpot

使用 CRM CTI 連接器時，不需要特殊設定，整合預設就會將互動資料儲存到 CRM 中。

***

### 透過 API 的自訂整合

如果你的代理人使用原生 Zoom Workplace 應用程式或 ZCC Smart Embed，你會需要一個自訂解決方案來傳送互動資料。主要做法是使用 Zoom 聯絡中心 API。

透過 API 存取互動資料主要有兩種方式：

* **輪詢：** 定期查詢 Zoom API，查看是否有新的互動資料可用。
* **Webhook：** 一旦逐字稿準備完成，立即接收 Zoom 傳送的即時通知。

另外還有第三種做法， **Flow Events 整合**，可適用於某些資料類型。

#### <mark style="color:藍色;">輪詢 Zoom 聯絡中心 API</mark>

若要下載互動資料，你必須查詢適當的 ZCC API 端點。請注意，不同類型的資料來自不同的 API，因此你很可能需要為每個相關端點建立輪詢邏輯。

Reports V2（CX Analytics）中的許多與互動相關 API 現在都支援結束時間篩選，並使用 `end_time_from` 與 `end_time_to`。在可用時，請優先使用這些參數，讓你的輪詢作業根據互動實際結束的時間來擷取互動。這有助於減少遺漏記錄，因為完整的互動資料（包括 report V2 資料）會在互動結束時完成定稿。

| 若要取得這些資料……                    | 請輪詢此 API……                                                                                                                                                                                                                                                                                                            | 使用此欄位……          | 附註：                  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------------------- |
| <p>錄音媒體檔</p><p>（語音與視訊頻道）</p>  | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/recordings/get/contact_center/recordings">列出錄音</a> 或</p><p>列出互動錄音</p>                                                                                                                                                                             | `download_url`   | 需要為佇列啟用通話錄音。         |
| <p>錄音逐字稿</p><p>（語音與視訊頻道）</p>  | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/recordings/GET/contact_center/recordings">列出錄音</a> 或</p><p>列出互動錄音</p>                                                                                                                                                                             | `transcript_url` | 需要啟用通話錄音與轉錄。         |
| <p>逐字稿</p><p>（訊息頻道）</p>       | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/engagements/get/contact_center/engagements/{engagementId}">取得一筆互動</a> 或</p><p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/reports-v2-cx-analytics/get/contact_center/analytics/log/historical/engagement">列出歷史互動日誌資料</a></p> | `transcript_url` | 訊息頻道預設已啟用逐字稿。        |
| <p>處置結果</p><p>（所有頻道）</p>      | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/engagements/get/contact_center/engagements/{engagementId}">取得一筆互動</a> 或</p><p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/reports-v2-cx-analytics/get/contact_center/analytics/log/historical/engagement">列出歷史互動日誌資料</a></p> | `dispositions`   | 一個處置結果物件陣列。          |
| <p>備註</p><p>（所有頻道）</p>        | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/engagements/get/contact_center/engagements/{engagementId}">取得一筆互動</a> 或</p><p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/reports-v2-cx-analytics/get/contact_center/analytics/log/historical/engagement">列出歷史互動日誌資料</a></p> | `notes`          | 一個備註物件陣列。            |
| <p>語音信箱媒體檔</p><p><br><br></p> | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/inboxes/GET/contact_center/inboxes/messages">列出帳戶的收件匣訊息</a> <strong>或</strong></p><p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/inboxes/GET/contact_center/inboxes/{inboxId}/messages">列出收件匣的訊息</a></p>                     | `download_url`   | 適用於在聯絡中心收件匣中留下的語音信箱。 |
| 語音信箱逐字稿                       | <p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/inboxes/GET/contact_center/inboxes/messages">列出帳戶的收件匣訊息</a> <strong>或</strong></p><p><a href="https://developers.zoom.us/docs/api/contact-center/#tag/inboxes/GET/contact_center/inboxes/{inboxId}/messages">列出收件匣的訊息</a></p>                     | `transcript_url` | 需要為收件匣啟用轉錄功能。        |

{% hint style="danger" %}
**警告**

這些 Zoom API 提供的下載 URL（`download_url`, `transcript_url`, `playback_url`等等）是 **不** 公開連結。它們是為程式化存取而設計，並需要 API 驗證（例如，在 Authorization 標頭中提供存取權杖）才能下載相關檔案。

這表示：

* 你不能直接把這些 URL 儲存在 CRM 中讓使用者點擊。使用者在瀏覽器中點擊連結時不會通過驗證，下載也會失敗。
* 正確的做法是讓你的後端服務使用該 URL 取得檔案。接著，你的服務可以將檔案儲存在你自己的系統中（例如 Amazon S3、Azure Blob Storage，或 CRM 的檔案儲存空間），再從那裡提供給使用者安全的連結。
  {% endhint %}

{% hint style="warning" %}
**提醒**

**處理延遲 - 語音與視訊錄音：**

這些資料不會在通話結束的瞬間就可用。音訊必須先經過處理並上傳，長時間通話可能需要幾分鐘。為確保不會漏掉錄音，請將 `query_date_type` 參數設定為 `recording_end_time` ，在輪詢 List recordings API 時使用。這會依據處理完成的時間來擷取資料，而不是依據通話結束時間。

對於 Reports V2（CX Analytics）以互動為中心的對帳作業，請使用重疊的時間區間並搭配 `end_time_from` 與 `end_time_to` ，以便為延遲處理和暫時性傳送問題提供安全緩衝。
{% endhint %}

如需更多關於 Zoom 聯絡中心 API 的資訊，請參閱 [聯絡中心 API](https://developers.zoom.us/docs/api/contact-center/) 文件。

#### <mark style="color:藍色;">使用 Webhooks 即時事件</mark>

若想採取更即時、以事件驅動的方式，你可以訂閱 ZCC Webhooks。這是近乎即時整合最有效率的方法。

**運作方式**

1. 在 Zoom App Marketplace 訂閱適當的事件。
2. 當事件發生時，Zoom 會將通知傳送到你的 webhook URL（或 WebSocket 連線）。
3. 事件負載包含你需要的資料，可能是直接包含，或以 URL/ID 的形式提供，以便進行後續 API 呼叫。

**用於互動資料的常見 Webhook 事件**

* **互動結束資料已就緒：** contact\_center.cx\_engagement\_end\_data\_ready（表示互動結束報告 V2 資料已可擷取）
* **語音／視訊錄音：** contact\_center.recording\_completed（提供一個 `download_url`)
* **語音／視訊逐字稿：** contact\_center.recording\_transcript\_completed（提供一個 `transcript_url`)
* **訊息逐字稿：** contact\_center.engagement\_messaging\_transcript\_completed（提供一個 `transcript_url`)
* **附註：** contact\_center.engagement\_note\_added（提供一個 `note` 欄位，內含備註資料）
* **處置結果：** contact\_center.engagement\_disposition\_added（提供一個 `disposition_name` 欄位，內含處置結果資料）

**建議模式：在互動資料就緒時觸發擷取**

當你收到 `contact_center.cx_engagement_end_data_ready`時，請將其視為該互動的結束報告 V2 資料已完成的訊號。此時，呼叫 Historical Engagement log data API 以及其他相關 API 來收集最終資料集。在此事件中，請使用 `engagement_id` 作為查詢鍵，然後從你需要的端點取得完整的互動產物。

{% hint style="warning" %}
**提醒**

* **注意多個事件：** 這項 `note_added` 與 `disposition_added` 事件可能會針對單一互動觸發多次（例如，若代理人儲存多則備註，或通話被轉接）。你的應用程式邏輯必須能夠處理這種情況。
* **建立冗餘機制：** 事件傳遞並不總是 100% 可靠保證（例如，你的端點或 WebSocket 連線可能暫時離線）。
* **備援策略：** 我們建議使用輪詢 API 搭配 `end_time_from` 與 `end_time_to` 時間窗來執行對帳，以捕捉遺漏的事件並彌補資料缺口。
  {% endhint %}

如需更多關於 Zoom 聯絡中心 Webhook/WebSocket 事件的資訊，請參閱 [聯絡中心 Webhooks](https://developers.zoom.us/docs/api/contact-center/events/) 文件。

#### <mark style="color:藍色;">Flow Events 整合</mark>

對於某些資料類型，你可以在 ZCC Flow 編輯器中使用 JavaScript Event Script，直接將資料推送到外部系統。

**支援的資料與限制：**

* **處置結果：** 可透過 `global_system.Engagement.disposition` 變數，在所有傳入互動頻道類型上存取。
* **逐字稿：** 僅可用於傳入訊息互動（例如 Web Chat），並透過 `global_system.Engagement.transcript` 變數，在所有傳入互動頻道類型上存取。
* **多個 Flow：** 在你的設定中使用多個 Flow 時，尤其是當某個 Flow 使用 `RouteTo` 小工具連接到另一個 Flow 時，務必要確保所有 Flow 中都正確設定了相同的 Event Scripts 和觸發條件。

這種方法在訊息 Flow 中最具威力，因為你可以在單一事件中同時結合逐字稿與處置結果。

**設定步驟**

請依照以下步驟設定你的 flow：

{% stepper %}
{% step %}
**新增 Event Script**

在你的 ZCC Flow 中（例如 Web Chat flow），點選 Start 小工具。

找到 Event Scripts，並新增適用於下列事件的 Event Script，例如 Engagement Closed 和／或 Disposition Saved。

<div align="left"><figure><img src="/files/b8479438903481d8b93cc40eaab35521b5564b55" alt="Flow screen showing a welcome message and events."><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**新增你的自訂 JavaScript**

以下範例會同時擷取處置結果與逐字稿，然後將它們一起傳送到外部 API。

```javascript
async function main () { 
  try {
    // 從其變數取得處置結果物件
    const disposition_data = var_get()['global_system.Engagement.disposition'];
    
    // 取得完整的逐字稿物件
    const transcript_data = await req.get(var_get()['global_system.Engagement.transcript']);

    // 準備一個包含你要傳送之所有資料的負載
    const payload_to_send = {
      disposition: disposition_data.data.result,
      transcript: transcript_data.data.result.transcript
    };

    // 定義資料的目的地
    const external_api_url = '<replace-with-your-api-endpoint>';
    
    // 將合併後的資料傳送到你的外部系統
  	const response = await req.post(external_api_url, payload_to_send);
    
    // 記錄外部系統的回應以便除錯
    log.debug("外部 API 回應：" + JSON.stringify(response.data));
    
  } catch (error) {
    log.debug("逐字稿事件指令碼中發生錯誤：" + error);
  }
}
```

{% endstep %}
{% endstepper %}

***

### 摘要與建議

選擇最符合你的代理人工作流程與技術資源的整合方法。

| 如果你的代理人使用……                      | 那麼你的最佳選擇是……                 | 重點考量：                                                                                                                                                                                         |
| -------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 受支援 CRM 中的 ZCC CTI 連接器           | 內建整合                        | <ul><li>最簡單的路徑</li><li>不需要程式碼</li><li>互動資料同步已內建</li></ul>                                                                                                                                     |
| Zoom Workplace 應用程式或 Smart Embed | API Webhooks 加上以結束時間篩選的輪詢對帳 | <ul><li>用途 <code>contact\_center.cx\_engagement\_end\_data\_ready</code> 作為你的擷取觸發條件</li><li>接著再以 <code>end\_time\_from</code>/<code>end\_time\_to</code> 時間窗</li><li>提升效率，同時減少遺漏的互動</li></ul> |
| 傳入訊息 Flow（且需要推送資料）               | Flow Event Scripts          | <ul><li>小眾，但功能強大</li><li>需要 JavaScript</li><li>最適合用於傳送訊息逐字稿與處置結果</li></ul>                                                                                                                    |

透過了解這些不同途徑，你可以建置一個穩健且可靠的整合，為你提供客戶互動的完整視圖。將事件觸發的擷取與以結束時間篩選的對帳結合起來，有助於你減少不必要的 API 呼叫，同時提升完整性。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://library.zoom.com/technical-library/zh-tw/shang-wu-fu-wu/zoom-contact-center/expert-insights/integrate-engagement-data.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.