> 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/shang-ye-ban-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，查看是否有新的互动数据在线。
* **Webhooks：** 一旦转写文字准备就绪，就从 Zoom 接收实时通知。

另外还有第三种方法， **Flow Events 集成**，它适用于某些数据类型。

#### <mark style="color:蓝色;">轮询 Zoom 呼叫中心 API</mark>

要下载互动数据，您必须查询相应的 ZCC API 端点。请注意，不同类型的数据来自不同的 API，因此您很可能需要为每个相关端点构建轮询逻辑。

Reports V2（CX 分析）中的许多与互动相关的 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>                                                                                                                                                                             | `转写文字_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> | `转写文字_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> | `处置`           | 一个处置对象数组。           |
| <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> | `备注`           | 一个备注对象数组。           |
| <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>                     | `转写文字_url`     | 需要为收件箱启用转写。         |

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

下载 URL（`download_url`, `转写文字_url`, `playback_url`，等等）由这些 Zoom API 提供， **不** 是公开链接。它们专为程序化访问而设计，并且需要 API 身份验证（例如，在 Authorization 标头中使用访问令牌）才能下载相关文件。

这意味着：

* 你不能直接将这些 URL 保存在 CRM 中让用户点击。用户在浏览器中点击该链接时不会通过身份验证，下载将会失败。
* 正确的方法是由你的后端服务使用该 URL 来获取文件。然后，你的服务可以将文件存储到你自己的系统中（例如 Amazon S3、Azure Blob Storage 或你 CRM 的文件存储），并从那里向用户提供安全链接。
  {% endhint %}

{% hint style="warning" %}
**请注意**

**处理延迟 - 语音和视频录制：**

这类数据不会在呼叫结束的瞬间就在线。音频必须先经过处理并上传，这对于较长的呼叫可能需要几分钟。为了确保你不会错过录制，请设置 `query_date_type` 参数用于 `录音结束时间` 在轮询录音列表 API 时。此操作根据处理完成时间获取数据，而不是根据呼叫结束时间。

对于 Reports V2（CX 分析）的以互动为中心的对账作业，请使用重叠的时间窗口，并配合 `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. 该 事件 & 活动 &直播 载荷包含你需要的数据，或者直接包含这些数据，或者作为后续 API 呼叫的 URL/ID。

**用于互动数据的常见 Webhook 事件**

* **参与结束数据已准备好：** 联系人\_center.cx\_engagement\_end\_data\_ready（表示互动结束报告 V2 数据已准备好可检索）
* **语音/视频录制：** 联系人\_center.recording\_completed (提供一个 `download_url`)
* **语音/视频转写文字：** 联系人\_center.recording\_转写文字\_completed（提供一个 `转写文字_url`)
* **发送消息转写文字：** 联系人\_center.engagement\_发送消息\_转写文字\_completed（提供一个 `转写文字_url`)
* **备注：** 联系人\_center.engagement\_note\_added（提供一个 `备注` 包含备注数据的字段）
* **处置：** 联系人\_center.engagement\_处置\_added（提供一个 `处置_name` 包含处置数据的字段）

**推荐模式：当交互数据准备就绪时触发检索**

当你收到 `联系人_center.cx_engagement_end_data_ready`时，请将其视为该互动的 engagement-end 报告 V2 数据已完成的信号。此时，呼叫 Historical Engagement log data API 和任何其他相关 API 以收集最终数据集。在此事件 & 活动 &直播中，请使用 `engagement_id` 作为查找键，然后从您所需的端点获取完整的互动工件。

{% hint style="warning" %}
**请注意**

* **注意多个事件 & 活动 &直播：** 该 `note_added` 和 `处置_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 事件 & 活动 &直播 集成</mark>

对于某些数据类型，您可以使用 JavaScript 事件 & 活动 &直播 脚本从 ZCC Flow 编辑器直接将数据推送到外部系统。

**支持的数据和限制：**

* **处置：** 可通过以下方式访问所有拨入互动频道类型 `global_system.Engagement.处置` 变量。
* **转写文字：** 仅可用于拨入发送消息互动（例如，Web 聊天）时使用的 `global_system.Engagement.转写文字` 变量。
* **多个流程：** 在配置中使用多个流程时，尤其是当某个流程使用 `RouteTo` 小组件连接到另一个流程时，务必确保在所有流程中都正确配置相同的 事件 & 活动 &直播 脚本和触发器。

这种方法在发送消息流程中最为强大，在该流程中，您可以将转写文字和处置结合到单个 事件 & 活动 &直播 中。

**配置步骤**

请按照以下步骤配置您的流程：

{% stepper %}
{% step %}
**添加一个事件 & 活动 &直播 脚本**

在您的 ZCC 流程中（例如，Web 聊天流程），点击 Start 小组件。

找到事件 & 活动 &直播 脚本，并为事件 & 活动 &直播 添加一个事件 & 活动 &直播 脚本，例如互动已关闭和/或处置已保存。

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

{% step %}
**添加您的自定义 JavaScript**

以下示例会检索处置和转写文字，然后将它们一起发送到外部 API。

```javascript
async function main () { 
  try {
    // 从其变量中获取处置对象
    const 处置_data = var_get()['global_system.Engagement.处置'];
    
    // 获取完整的转写文字对象
    const 转写文字_data = await req.get(var_get()['global_system.Engagement.转写文字']);

    // 准备一个包含你要发送的所有数据的负载
    const payload_to_send = {
      处置: 处置_data.data.result,
      转写文字: 转写文字_data.data.result.转写文字
    };

    // 定义你的数据目的地
    const external_api_url = '<替换为你的 API 端点>';
    
    // 将合并后的数据发送到你的外部系统
  	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>Engagement 数据同步已内置</li></ul>                                                                                                                          |
| Zoom Workplace 应用或 Smart Embed | API Webhooks 加上按结束时间筛选的轮询对账 | <ul><li>使用 <code>联系人\_center.cx\_engagement\_end\_data\_ready</code> 作为你的检索触发器</li><li>然后与 <code>end\_time\_from</code>/<code>end\_time\_to</code> 时间窗口</li><li>在减少遗漏的互动的同时提高效率</li></ul> |
| 一个拨入发送消息流程（以及需要推送数据）           | 流程 事件 & 活动 &直播 脚本           | <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/shang-ye-ban-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.