> 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).

# 集成交互数据

作者：Justin Steinberg

### 概述

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 管理员门户。在 [管理员中心](https://zoom.com/account)，转到 CX management → 呼叫中心 → 集成 → [应用程序](https://zoom.com/cci/index/admin#/admin-integrations).

找到相关的 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>                                                                                                                                                                             | `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` 参数设为 `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 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`)
* **语音/视频转写文字：** 联系人中心.录音\_转写文字\_已完成（提供一个 `转写文字_url`)
* **发送消息转写文字：** 联系人中心.互动\_发送消息\_转写文字\_已完成（提供一个 `转写文字_url`)
* **备注：** 联系人中心.互动\_备注\_已添加（提供一个 `备注` 包含备注数据的字段）
* **处置：** 联系人中心.互动\_处置\_已添加（提供一个 `处置名称` 包含处置数据的字段)

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

当你收到 `联系人_center.cx_engagement_end_data_ready`，将其视为你收到的信号，表示该互动结束报告 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 事件 & 活动 &直播 的更多信息，请参见 [呼叫中心 Webhook](https://developers.zoom.us/docs/api/contact-center/events/) 文档。

#### <mark style="color:蓝色;">Flow 事件 & 活动 &直播 集成</mark>

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

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

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

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

**配置步骤**

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

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

在你的 ZCC 流程（例如，Web 聊天流程）中，单击 Start 小部件。

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

<div align="left"><figure><img src="https://2325962437-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FctBXUMeBy4rtLMmMkKRG%2Fuploads%2Fgit-blob-608a0caccf5697f0cda911a59ba832b2f5cf3fd6%2Fimage.png?alt=media" alt="Flow screen showing a welcome message and events."><figcaption></figcaption></figure></div>
{% endstep %}

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

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

```javascript
async function main () { 
  尝试 {
    // 从其变量中获取处置对象
    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>联系人\_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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.