> 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. 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管理] → \[コンタクトセンター] → \[連携] → \[ [アプリケーション](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 を介してエンゲージメントデータにアクセスする主な方法は 2 つあります：

* **ポーリング：** 新しいエンゲージメントデータがオンラインで利用可能かどうかを確認するため、Zoom APIに定期的に問い合わせます。
* **Webhooks:** 文字起こしの準備ができ次第、Zoomからリアルタイムで通知を受け取ります。

3つ目の方法もあります。 **Flow Events連携**。これは特定のデータ型で機能します。

#### <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>                                                                                                                                                                                          | `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" %}
**警告**

ダウンロード 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 イベント**

* **エンゲージメント終了データの準備完了:** 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` 1 回のエンゲージメントでイベントが複数回発生することがあります（たとえば、エージェントが複数のメモを保存した場合や、通話が転送された場合など）。アプリケーションのロジックでこれに対応できる必要があります。
* **冗長性を組み込む:** イベントの配信は常に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.文字起こし` 変数。
* **複数のフロー:** 設定内で複数のFlowを扱う場合、特にあるFlowが次を使用しているときは `RouteTo` 別の Flow に接続するウィジェットを使用する場合は、すべての Flow で同一のイベントスクリプトとトリガーが正しく設定されていることを確認することが重要です。

この方法は、文字起こしと処理の両方を単一のイベントに組み合わせることができるメッセージフローで最も強力です。

**設定手順**

以下の手順に従ってフローを設定する:

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

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

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

<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
非同期関数 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 = '<replace-with-your-api-エンドポイント>';
    
    // 結合したデータを外部システムに送信する
  	const response = await req.post(external_api_url, payload_to_send);
    
    // トラブルシューティングのために外部システムからの応答をログに記録する
    log.debug("External 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>contact\_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/ja/bijinesusbisu/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.
