> 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/ja/bijinesusbisu/zoom-contact-center/expert-insights/integrate-engagement-data.md).

# エンゲージメントデータを連携

Justin Steinbergによる執筆

### 概要

Zoom コンタクトセンターは、通話レコーディング、文字起こし、エージェントのメモ、結果を含む、すべての顧客対応中に貴重なエンゲージメントデータを生成します。Zoom コンタクトセンターを使用する際に、統合された顧客ビューの作成、効果的なエージェントコーチングの実現、またはコンプライアンス要件への対応のため、外部システム（CRMやその他の記録システムなど）にエンゲージメントデータを保存する方法をご確認ください。

エージェントの業務効率向上に応じて最適なアプローチを選択できるよう、さまざまな連携方法を解説します。

最適な方法は、主に次の重要な要素によって決まります。 **エージェントが対応を処理するアプリケーション**。ここでは、次の2つの選択肢について説明します。

1. CRM内で、標準搭載のZCC CRM CTI コネクタを使用するエージェント。
2. ZCC APIおよびWebhookを使用したカスタムソリューションが必要な、Zoom Workplace アプリで業務を行うエージェント。

***

### 標準搭載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を介してエンゲージメントデータにアクセスする主なアプローチは2つあります。

* **ポーリング：** 新しいエンゲージメントデータがオンラインかどうかを確認するため、Zoom APIを定期的に照会します。
* **Webhook：** 文字起こしの準備が整い次第、Zoomからリアルタイムの通知を受け取ります。

3つ目のアプローチとして、 **フローイベント連携**があり、これは特定のデータタイプで機能します。

#### <mark style="color:青;">Zoom コンタクトセンターAPIのポーリング</mark>

エンゲージメントデータをダウンロードするには、適切なZCC APIエンドポイントを照会する必要があります。データの種類ごとに異なるAPIから取得されるため、関連する各エンドポイント用のポーリングロジックを構築する必要がある可能性が高い点に注意してください。

Reports V2（CX 分析）内の多くのエンゲージメント関連APIは、現在、次のパラメータによる終了時刻フィルタリングをサポートしています。 `end_time_from` および `end_time_to`。利用可能な場合は、ポーリングジョブが実際に終了した時点に基づいてエンゲージメントを取得できるよう、これらのパラメータを優先してください。完全なエンゲージメントデータ（報告 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:青;">リアルタイム イベントに Webhook を使用する</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（a を提供する `download_url`)
* **音声/ビデオ文字起こし:** 連絡先\_center.recording\_文字起こし\_completed (aを提供する `文字起こし_url`)
* **メッセージ 文字起こし:** 連絡先\_center.engagement\_メッセージ\_文字起こし\_completed（1つを提供する `文字起こし_url`)
* **注：** 連絡先\_center.engagement\_note\_added（1つを提供する `メモ` メモデータを含むフィールド）
* **処理:** 連絡先\_center.engagement\_処理\_added（1つを提供する `処理名` 処理データを含むフィールド）

**推奨パターン: エンゲージメントデータの準備ができたら取得をトリガー**

受信したら `連絡先_center.cx_engagement_end_data_ready`、それを、そのエンゲージメントについての engagement-end 報告 V2 データが完了した合図として扱います。その時点で、Historical Engagement log data API およびその他の関連 API を通話し、最終データセットを収集してください。このイベントでは、 `engagement_id` を検索キーとして使用し、その後、必要なエンドポイントから完全なエンゲージメント成果物を取得します。

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

* **複数のイベントに注意:** この `note_added` および `処理_added` イベントは、1つのエンゲージメントに対して複数回発火することがあります（たとえば、エージェントが複数のメモを保存した場合や、通話が転送された場合です）。アプリケーションロジックはこれを処理できる必要があります。
* **冗長性を組み込む:** イベントの配信は常に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:青;">フロー イベント連携</mark>

一部のデータ型については、JavaScript イベントスクリプトを使用して、ZCC Flow エディタから外部システムへデータを直接送信できます。

**対応データと制限事項：**

* **処理:** 以下を使用して、すべての着信エンゲージメントチャネルタイプでアクセスできます。 `global_system.Engagement.処理` 変数。
* **文字起こし:** 着信メッセージのエンゲージメント（たとえば、Web チャット）でのみアクセス可能です。以下を使用して `global_system.Engagement.文字起こし` 変数。
* **複数のフロー:** 設定内で複数のフローを使用する場合、特に1つのフローが以下を使用している場合は、 `RouteTo` ウィジェットを使って別のフローに接続する際、同一のイベント スクリプトとトリガーがすべてのフローで適切に設定されていることを確認することが重要です。

この方法はメッセージ フローで最も効果的であり、文字起こしと処理の両方を1つのイベントに組み合わせることができます。

**設定手順**

次の手順に従ってフローを設定する：

{% stepper %}
{% step %}
**イベントスクリプトを追加**

ZCCフロー（例：Web チャットフロー）で、［Start］ウィジェットをクリックします。

［イベントスクリプト］を見つけ、［エンゲージメント終了］や［処理保存］などのイベント用にイベントスクリプトを追加します。

<div align="left"><figure><img src="https://2994873379-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 () { 
  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 Webhookと終了時刻でフィルタリングされたポーリング照合 | <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/ja/bijinesusbisu/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.