-
Qualtrics Platform -
Customer Journey Optimizer -
XM Discover -
Qualtrics Social Connect
XM Discoverリンク受信コネクタ
XM Discoverリンク受信コネクターについて
XM Discoverリンク受信コネクターを使用すると、フィールドマッピング、変換、フィルタ、ジョブウォッチなど、コネクターフレームワークで提供されるすべての機能を活用しながら、REST APIエンドポイントを介してXMデータをXM Discoverにプッシュできます。
サポートされるデータ書式
次のデータ型は JSON 形式でのみサポートされています:
- 個人フィードバック
- デジタルインタラクション
- 成績証明書の呼出
コネクターを設定する前に、XM Discoverにインポートするフィールドを表すサンプルファイルを作成します。必須フィールドとファイル形式の詳細については、上記のリンク先のページを参照してください。
コネクタ内でダウンロードできる、特定のデータ形式のテンプレートファイルもあります。
- チャット
- チャット (デフォルト): 標準のデジタルインタラクションデータに使用します。
- Amazon Connect: Amazon Connect チャットに固有のデジタルインタラクションに使用します。
- 電話
- コール (デフォルト): 標準コール成績証明書データに使用します。
- Verint: Verint 固有のコール成績証明書に使用します。
- フィードバック
- Dynamics 365: Microsoft Dynamics データに使用します。
XM Discoverリンク受信コネクタージョブの作成
- [ジョブ] タブで、[新しいジョブ] をクリックします。
![[New Job] ボタンをクリックします。](https://www.qualtrics.com/m/assets/support/wp-content/uploads//2023/05/new-job-1.png)
- XM Discoverリンクジョブをクリックします。
- ジョブを特定できるように、ジョブに名前を付けます。
- データをロードするプロジェクトを選択します。
- 目的がわかるように、ジョブに説明を付けます。
- [次へ] をクリックします。
- 権限モードを選択するか、XM Discoverに接続する方法：
- APIキー：XM Discover APIトークンを使用して接続します。
- OAuth 2.0: XM Discover 認証サービスで提供されるクライアント ID およびクライアントシークレットを使用して接続します。XMサクセスマネージャーに連絡して、この方法を要求してください。
- [次へ] をクリックします。
- データ形式 (チャット (デジタル)、電話、またはフィードバック) を選択します。
- 必要に応じて、テンプレートを選択し、ここリンクをクリックしてテンプレートファイルをダウンロードします。
- 文書ノードを含む JSON のサブセットへの JSON パスを入力します。文書がルートノードレベルにある場合は、この項目を空白のままにします。
- [クリックしてアップロードするファイルを選択] ボタンをクリックし、コンピュータ上のサンプルファイルを選択します。
- ファイルのプレビューが表示されます。プレビューではなくエラーメッセージまたはローファイルの内容が表示される場合は、選択したデータ書式オプションに問題がある可能性があります。ファイルのトラブルシューティングについては、「サンプルファイルのエラー」ページを参照してください。
- [次へ] をクリックします。
- 必要に応じて、データマッピングを調整します。XM Discoverのマッピングフィールドの詳細については、「データマッピング」サポートページを参照してください。デフォルトデータマッピングセクションには、このコネクタに固有のガイダンスが含まれています。
- [次へ] をクリックします。
- 必要に応じて、データ代替ルールおよび編集ルールを追加して、機密データを非表示にしたり、顧客フィードバックおよびインタラクションの特定の単語およびフレーズを自動的に置換したりすることができます。詳細については、データ置換と編集のサポートページを参照してください。
- [次へ] をクリックします。
- 必要に応じて、受信データをフィルタリングするコネクタフィルタを追加して、インポートされるデータを制限することができます。
- [次へ] をクリックします。
- 重複伝票の処理方法を選択します。詳細については、重複処理を参照してください。
- [次へ] をクリックします。
- 設定をレビューします。特定の設定を変更する必要がある場合は、編集ボタンをクリックして、コネクタ設定のそのステップに移動します。
- APIドキュメントリンクには、XM Discoverにデータを送信するために使用されるAPIエンドポイントが含まれています。詳細については、API エンドポイントへのアクセスを参照してください。
- [完了] をクリックして設定を保存します。
デフォルトデータマッピング
このセクションでは、XM Discover インバウンドリンクジョブのデフォルトフィールドについて説明します。
項目のマッピング時には、以下のデフォルト項目を使用することができます。
- feedback_type: フィードバックタイプは、データをそのタイプに基づいて識別するのに役立ちます。これは、プロジェクトにさまざまなタイプのデータ（アンケートやソーシャルメディアフィードバックなど）が含まれる場合にレポートに役立ちます。この項目は編集可能です。デフォルトでは、この属性の値はに設定されています。
- コール記録の “コール”
- デジタルインタラクションのための “チャット”
- 個人フィードバックのための「フィードバック」
- カスタム変換を使用して、カスタム値を設定できます。
- source: ソースは、特定のソースから取得されたデータを識別するのに役立ちます。これは、サーベイやモバイルマーケティングキャンペーンの名称など、データの発生源を示すあらゆるものにできます。この項目は編集可能です。デフォルトでは、この属性の値は「XM Discover Link」に設定されています。カスタム変換を使用して、カスタム値を設定できます。
- richVerbatim: この項目は会話データ (コールやチャットの成績証明書など) に使用され、編集できません。XM Discoverでは、richVerbatim フィールドに会話詞形式を使用します。この形式では、会話ビジュアライゼーションのロックを解除するために必要なダイアログ固有のメタデータ (講演者回転、沈黙、会話イベントなど) および拡張 (開始時刻、期間など) がサポートされます。この口頭でのフィールドには、クライアント側と代表者の会話側を追跡するための「子」フィールドが含まれます。
- clientVerbatim は、クライアントの会話側を追跡します。
- agentVerbatim は、会話の代理人（エージェント）側を追跡します。
- unknown は、会話の未知の側を追跡します。
-
ヒント: 変換は対話的な完全一致フィールドではサポートされていません。異なるタイプの会話データに対して、同じことをそのまま使用することはできません。プロジェクトで複数のタイプの会話がホストされるようにする場合は、会話タイプごとに別々の会話言語ペアを使用します。
- clientVerbatim: この項目は対話式データに使用され、編集可能です。このフィールドでは、コールおよびチャットインタラクションにおける会話のクライアント側を追跡します。デフォルトでは、このフィールドは以下にマッピングされます。
- clientVerbatimChat (デジタルインタラクションの場合)
- clientVerbatimCall (コールインタラクションの場合)。
- agentVerbatim: この項目は対話式データに使用され、編集可能です。このフィールドでは、コールおよびチャットインタラクションにおける会話の担当者の側を追跡します。デフォルトでは、このフィールドは以下にマッピングされます。
- agentVerbatimChat (デジタルインタラクションの場合)
- コールインタラクションの agentVerbatimCall。
- 不明: この項目は対話式データに使用され、編集可能です。この項目は、コールおよびチャットインタラクションにおける対話の不明な側を追跡します。デフォルトでは、この項目は以下のようにマッピングされます。
- デジタルインタラクションのための UnknownVerbatimChat
- コールインタラクションの unknownVerbatimCall。
- document_date: ドキュメント日付は、ドキュメントに関連付けられた主要な日付フィールドです。この日付は、XM Discoverのレポート、トレンド、アラートなどで使用されます。伝票日付には、以下のいずれかのオプションを選択します。
- conversationTimestamp (対話型データ用): 会話全体の日時。
- ソースデータに他の日付項目が含まれている場合は、項目名のドロップダウンメニューから日付項目を選択することで、そのいずれかを伝票日付として設定することができます。
- ユーザ定義項目を追加して、特定の日付を設定することもできます。
- natural_id: 自然 ID はドキュメントの一意の識別子として機能し、重複を正しく処理することができます。Natural ID には、以下のいずれかのオプションを選択します。
- conversationId (対話型データ用): メッセージのやり取り全体の一意の ID。
- 項目名のデータから、任意のテキストまたは数値項目を選択します。
- カスタムフィールドを追加することで、ID を自動的に生成します。
- feedback_provider: フィードバックプロバイダは、特定のプロバイダから取得したデータを特定するのに役立ちます。XM Discoverリンクをアップロードする場合、この属性の値は「XM Discoverリンク」に設定され、編集できません。
- job_name: ジョブ名は、アップロードに使用されたジョブの名前に基づいてデータを識別するのに役立ちます。ページ上部のジョブ名ボックスで、またはジョブオプションメニューを使用して、この属性の値を変更することができます。
- loadDate：ロード日は、ドキュメントがXM Discoverにアップロードされた日付を示します。この項目は自動的に設定され、編集することはできません。
上記のフィールドに加えて、インポートするカスタムフィールドをマッピングすることもできます。カスタムフィールドの詳細については、「データマッピング」サポートページを参照してください。
API エンドポイントへのアクセス
API エンドポイントは、REST APIリクエストを使用してデータをJSON形式で送信することで、XM Discoverにデータをアップロードするために使用されます。
このエンドポイントには、ジョブページからアクセスできます。
- ジョブのジョブオプションメニューでサマリを選択します。
- API Documentation リンクをクリックします。
- [印刷] ボタンをクリックして、このウィンドウのすべての情報を印刷可能な PDF としてダウンロードします。
- エンドポイント情報には、
が含まれます。- API URL: API 要求に使用される URL。
- メソッド：POST メソッドを使用して XM Discover にデータをロードします。
- ジョブ ID: 現在選択されているジョブの ID。
- JSON ペイロードの例は、要求本文セクションに含まれています。API 要求には 1 つのドキュメントのみを含める必要があり、サンプルペイロードにはフィールドのみを含めます。
- 応答セクションには、API 要求の可能な成功応答およびエラー応答が一覧表示されます。
- スキーマセクションにデータスキーマが表示されます。必須フィールドが必須の配列に含まれています。
APIによるXM Discoverリンクジョブの監視
XM Discover にログインせずに XM Discover ジョブのステータスを監視するには、ステータスAPIエンドポイントを呼び出します。これにより、最新のジョブ実行ステータス、特定のジョブ実行のメトリック、または特定の期間の累計メトリックを取得することができます。
ステータスエンドポイント情報
ステータスエンドポイントを呼び出すには、以下が必要です。
- API URL: https://na-data.clarabridge.net/v1/public/job/status/ <jobID> ?apiKey=<apiKey>
- <jobId> は、監視する XM Discover Link ジョブの ID です。
- <apiKey> は API トークンです。
- タイプ: REST HTTP を使用
- HTTP メソッド: GET メソッドを使用してデータを取得します。
入力要素
以下のオプションの入力エレメントを使用して、ジョブに関する追加メトリックを取得することができます。
- historicalRunId: 特定のアップロードセッションの ID。このエレメントが省略され、日付範囲が指定されていない場合、API 呼出は最新のジョブ実行ステータスを返します。このエレメントが省略され、日付範囲が指定されている場合、API 呼出により、指定された期間の累計メトリックが返されます。
- startDate: データを返す開始日付を定義します。
- endDate: 最終アップロードに基づいてデータを返す終了日付を定義します。このエレメントを省略し、startDate を指定すると、endDate は自動的に現在の日付に設定されます。
出力要素
必要な入力要素を入力すると、以下の出力要素が返されます。
- job_status: ジョブのステータス。
- job_failure_reason: ジョブが失敗した場合、失敗の理由。
- run_metrics: ジョブによって処理されるドキュメントに関する情報。以下のメトリックが含まれます。
- SUCCESSFULLY_CREATED: 正常に登録された文書の数。
- SUCCESSFULLY_UPDATED: 文書の数が更新されました。
- SKIPPED_AS_DUPLICATES: 重複としてスキップされた伝票の数。
- FILTERED_OUT: ソース固有のフィルタまたはコネクタフィルタによって除外されたドキュメントの数。
- BAD_RECORD：クアルトリクスの会話形式に一致しない、処理のために送信されたデジタルインタラクションの数。
- SKIPPED_NO_ACTION: 非重複としてスキップされた文書の数。
- FAILED_TO_LOAD: ロードに失敗したドキュメントの数。
- 合計: このジョブの実行中に処理された伝票の合計数。
エラーメッセージ
ステータス API 要求に対して、以下のエラーメッセージが表示されることがあります。
- 401 権限なし: 認証に失敗しました。別の API キーを使用してください。
- 404 見つかりません: 指定された ID のジョブは存在しません。別のジョブ ID を使用してください。
要求の例
以下に、ジョブのステータスを取得する要求の例を示します。
curl --location --request GET 'https://na-data.clarabridge.net/v1/public/job/status/62da736987c9788b830918e0?apiKey=02e7a0e26b592632dd50f623e974fff6'
応答の例
以下は、失敗したジョブの応答の例です。
{
"job_status": "Failed",
"job_failure_reason": "{\"problem\":[{\"requestId":"RQ-MOB-f339aa58-71b6-4a1d-a67c-12b8d3439321","runsevert","description":"900 characters of 900 characters for attribute supportexperienceresp", length = 1043\" reason": "{\"failure_reason":[{\"requestId": "RQ-MO
","runseverity","description":"length"
",
", "status"
",
" successstatus\}
ペイロードの例
このセクションには、サポートされているタイプの構造化データ (フィードバック、チャット、コール) ごとに 1 つのサンプル JSON ペイロードが含まれています。
- ここをクリックして、フィードバック例のペイロードを表示します。
curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4e583f9142ae48a1090a76' \
--header 'Content-Type: application/json' \
--data-raw '{
"Standard JSON","Row_ID": "id43682",
"store_number": "226,1,1,0,0",
"address": "5916 W Loop 289 Lube_79bock" 良い仕事を続けてください。",
"LTR": 10,
"state": "TX",
"Rewards_Member": "MyBestBuy"
}'
- ここをクリックして、チャットサンプルペイロードを表示します。
curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4d77656afa99b0396ef959' \
--header 'Content-Type: application/json' \
--data-raw '{
"conversationId": "37854","
conversationTimestamp": "202007-30T12:15.000Z","content": {
" {contentType": "CHAT" {par
ticipantType"
、
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785201"
},
{
"participantId": "2",
"text": "こんにちは、今日開いていますか?"、
"timestamp": "2020-07-30T12:42:15.000Z",
"id" "id": "3785202"
},
"participantId": "1",
"text": "We are open from 17:00 to 23:00","timestamp": "20520-30T12:42:15.000Z",
"3785202",
"iscipantId",
使用できる名前",
"timestamp": "2020-07-30T12:42:15.000Z",
"id": "3785205"
}
]
,
"city": "Boston",
"source": "Facebook"
}'
- ここをクリックして、呼出例ペイロードを表示します。
curl --location --request POST 'https://na-data.clarabridge.net/v1/cb_link?apiKey=887fc11663c456f9f34844a8a8bdff64&jobId=5f4e564d9242ae6e6308ff04' \“
--header 'Content-Type: application/json' \
--data-raw '{
"conversationId": "462896","
conversationTimestamp": "2020-07-30T10:4:4
5.000Z" "content": {
"contentType" "CALL",,
"start": 22000,
"end": 32000
},
"
participant_id": "2",
"text": "Hi, I have a have a hin of questions.",
"start": 32000,
"end": 42000
},"contentSegmentType": "TURN"
,
,
"city": "Boston" call