> 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 和 Webhook 的自定义解决方案。

***

### 开箱即用的 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 分析）中的许多与互动相关的 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>                                                                                                                                                                             | `下载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>                     | `下载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（`下载URL`, `转写文字URL`, `playback_url`，等等）由这些 Zoom API 提供的是 **不是** 公共链接。它们旨在用于程序化访问，并且需要 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 分析）以参与为中心的对账任务，请使用重叠的时间窗口，并结合 `end_time_from` 和 `end_time_to` 以为延迟处理和临时传送问题提供安全缓冲。
{% endhint %}

有关 Zoom 呼叫中心 API 的更多信息，请参见 [呼叫中心 API](https://developers.zoom.us/docs/api/contact-center/) 文档。

#### <mark style="color:蓝色;">使用 Webhooks 处理实时事件</mark>

为了采用更即时、事件 & 活动 &直播驱动的方法，您可以订阅 ZCC webhook。这是实现接近实时集成的最高效方法。

**工作原理**

1. 在 Zoom App Marketplace 订阅相应的事件。
2. 当发生 事件 & 活动 &直播 时，Zoom 会向你的 Webhook URL（或你的 WebSocket 连接）发送通知。
3. 该 事件 & 活动 &直播 载荷包含你需要的数据，既可以直接提供，也可以作为后续 API 呼叫的 URL/ID。

**用于参与数据的常见 Webhook 事件**

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

**推荐模式：当参与数据就绪时触发检索**

当你收到 `联系人中心.cx_engagement_end_data_ready`，将其视为你的信号，表示该参与的 engagement-end report V2 数据已完成。此时，呼叫 历史参与日志数据 API 以及任何其他相关 API 来收集最终数据集。在这种事件 & 活动 &直播中，使用 `engagement_id` 作为你的查找键，然后从所需的端点获取完整的互动工件。

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

* **注意多个 事件 & 活动 &直播：** 该 `已添加备注` 和 `已添加处置` 事件 & 活动 &直播可能会针对单个互动触发多次（例如，如果座席保存了多条备注，或者呼叫被转接）。你的应用程序逻辑必须能够处理这一点。
* **内置冗余：** 事件 & 活动 &直播的投递并不总能 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 聊天流程），单击开始组件。

定位 事件 & 活动 &直播 脚本，并为 事件 & 活动 &直播 添加一个 事件 & 活动 &直播 脚本，例如 Engagement Closed 和/或 处置 已保存。

<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>互动数据同步已内置</li></ul>                                                                                                                             |
| Zoom Workplace 应用或 Smart Embed | API Webhooks 加上按结束时间筛选的轮询对账 | <ul><li>使用 <code>联系人中心.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.