ZendeskのData Export APIは、AIエージェントの潜在能力を最大限に引き出すための鍵となります。会話データをエクスポートして、多様なプラットフォームやアプリケーションに統合できるようにします。
ZendeskのAPIは、開発者、ビジネスアナリスト、ITプロフェッショナルを問わず、貴重なインサイトや会話のメタデータを安全かつ効率的に抽出できるシンプルなソリューションです。イノベーションの推進や、情報に基づく意思決定の支援を通じて、組織をさらなる成長へと導きます。
この記事では、次のトピックについて説明します。
組織IDの取得
この手順を実行できるのは、管理者ロールを付与されたユーザーのみです。
- 左側のサイドバーで「組織の管理」をクリックします。
メモ：AIエージェント - Advancedアプリが2024年10月7日以前に購入されているユーザーは、「ユーザー管理」>「組織の管理」をクリックしてください。
- 目的の組織をクリックしてプロフィールを開きます。
- ブラウザのURLアドレスバーに次のような組織IDが表示されます。
https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s
APIトークンの生成
APIトークンを生成できるのは、管理者ロールを付与されたユーザーのみです。
- 左側のサイドバーで「組織の管理」をクリックします。
メモ：AIエージェント - Advancedアプリが2024年10月7日以前に購入されているユーザーは、「ユーザー管理」>「組織の管理」をクリックしてください。
- 目的の組織をクリックしてプロフィールを開きます。
- 「APIキー」タブを選択します。
- 「生成」をクリックします。
- 「保存」をクリックします。
- APIキーをコピーして安全な場所に保管します。
「組織の管理」ページを閉じると、そのトークンにはアクセスできなくなります。以前に生成したトークンを紛失した場合は、「再生成」ボタンをクリックすることで、そのトークンを無効にできます。古いトークンは無効になり、新しく生成したトークンを使用できます。
APIについて
Data Export APIは、UTC（協定世界時）の午前0時に1日1回更新されます。更新プロセスには時間がかかることがあるため、UTCの早朝にインポートしておくと、データの準備が整った状態で作業を始められます。
EU用のAPI：POST - https://api.ultimate.ai/data-export/v3/get-signed-urls
米国用のAPI：POST - https://api.us.ultimate.ai/data-export/v3/get-signed-urls
ヘッダー
|
名前 |
必須 |
タイプ |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
本文
|
名前 |
必須 |
タイプ |
|---|---|---|
|
|
|
|
レスポンス
|
HTTPコード |
レスポンス |
|---|---|
|
200 |
|
|
401 |
権限がありません |
|
500 |
内部サーバーエラー |
メモ：
- ファイルのURLはリクエスト日から1日後に失効します。APIコールを再度実行すれば、有効なリンクを取得できます。
- 2024年1月1日まで遡ってデータを請求することができます。これ以前のデータが必要な場合は、Zendeskカスタマーサポートまでお問い合わせください。
ファイルのスキーマ
APIによって出力されるJSONドキュメントには、指定された日のすべての会話が含まれており、以下の構造に従います。
- ファイルは、個々の会話をオブジェクトで表すJSONオブジェクトのリストです。
- ファイル名は「conversation_bot-id_date_000000000000.json」の形式になります。
| プロパティ | 説明 | タイプ |
| "bot_id" | ボットの一意のID |
"bot_id": {
|
| "bot_name" | ボットの名前 |
"bot_name": {
|
| "conversation_id" | 生成された会話ID |
"conversation_id": {
|
| "platform_conversation_id" | CRM専用ID |
"platform_conversation_id": {
|
| "conversation_start_time" | UTCタイムゾーンに基づく会話の開始日時 |
"conversation_start_time": {
|
| "conversation_end_time" | UTCタイムゾーンに基づく会話の終了日時 |
"conversation_end_time": {
|
| "conversation_type" | 会話で特定された返信のタイプ。「ユースケース」、「ナレッジベース」、「ハイブリッド」、「その他」のいずれかの値をとります。 |
"conversation_type": {
|
| "language" | 会話の使用言語 |
"language": {
|
| "channel" | 会話のチャネル。メッセージングまたはメール |
"channel": {
|
| "labels" | 会話に関連付けられたラベルの全リスト |
"labels": {
|
| "segments" | 会話で確認されたすべてのセグメントのリスト。セグメントについてさらに詳しく |
"segments": {
|
| "conversations_data" |
会話に関連付けられたセッションパラメータ。パラメータに値を含むキーのリストです。未定義のキーはこのリストに含まれません。 メモ：
例： "conversations_data": {
|
"conversations_data": {
|
|
"test_mode"
|
会話がテスト会話かどうかを識別するフラグ |
"test_mode": {
|
| "conversation_status" | 会話の解決例：bot_handled |
"conversation_status": {
|
| "automated_resolution" | 会話を自動解決として評価した結果。自動解決の計算方法については、こちらをご覧ください。 |
"automated_resolutions": {
|
| "automated_resolution_reasoning" | 会話が自動解決としてマークされた理由を判断するために使用される根拠。 |
"automated_resolution_reasoning": {
|
| "last_resolution" |
会話の最終的な解決内容。情報提供済み、解決済み、エスカレーション済み、または未定義。 この機能は2026年2月28日に提供終了となります。予定される機能の提供終了についての詳細はこちら。 |
"last_resolution": {
|
| "triggered_replies" | 返信に関する詳細。たとえば、reply_id、language、reply_name、reply_type、intent_idといった情報が含まれます。 |
"triggered_replies": {
|
| "triggered_procedures" |
たとえば、procedure_id、intent_id、use_case_nameといった情報が含まれます。 このセクションは、トレーニング不要のAIエージェントの場合、またはトリガされた手順が存在しない場合に空になります。 |
"triggered_procedures": {
|
| "triggered_use_cases" |
ユースケースが対話として構成されているか、プロシージャとして構成されているかを識別するためのフラグ。 |
"triggered_use_cases": {
|
| "has_knowledge_response_attempt" | 会話がナレッジベース会話であるかどうか（少なくとも1つのナレッジベース回答を含む）を判定するためのフラグ。ナレッジベース回答が理解されたかどうか、技術的なエラーが発生したか、雑談であったかなどには関係なく、該当するすべての会話はナレッジベース会話として扱われます。 |
"has_knowledge_response_attempt": {
|
| "knowledge_notUnderstood_count" | ナレッジベースの会話で理解できなかったメッセージの数。自律型ナレッジベース応答の場合、これには、AIエージェントが質問を適切なナレッジソースに照合できず、応答を生成できなかった場合の補足質問が含まれる可能性があります。 |
"knowledge_notUnderstood_count": {
|
| "knowledge_responseGenerated_count" | ナレッジベースの会話で応答が生成されたメッセージの数。 |
"knowledge_responseGenerated_count": {
|
| "knowledge_errorOccurred_count" | ナレッジベースの会話でエラーが発生したメッセージの数。 |
"knowledge_errorOccurred_count": {
|
| "knowledge_escalationRequired_count" | ナレッジベースの会話でエスカレーションが必要になったメッセージの数。このステータスは、生成処理されたナレッジベース応答にのみ適用されます。 |
"knowledge_escalationRequired_count": {
|
| "knowledge_fallback_count" | ナレッジベースの会話でフォールバックされたメッセージの数。 |
"knowledge_fallback_count": {
|
| "knowledge_sources" | 会話で使用されたナレッジベースタイプ、記事タイトル、URLのリスト。 |
"knowledge_sources": {
|
| "bot_messages_count" | AIエージェントのメッセージの数 |
"bot_messages_count": {
|
| "visitor_messages_count" | カスタマーメッセージの数 |
"visitor_messages_count": {
|
| "not_understood_messages_count" | 理解されなかったメッセージの総数 |
"not_understood_messages_count": {
|
レスポンスの例
APIコールのレスポンスは、GETリクエストでアクセスできるGoogleストレージバケット内のファイルへのURLリンクになります。
{"date":"2024-05-03","urls":["https://storage.googleapis.com/production-eu-ultimateai-backend-data-export/files/your_bot_id/2024-05-0/conversation_your_bot_id_20240503_000000000000.json…"]} このファイルには、各会話が以下のフォーマットに従ってJSONオブジェクトとして格納されています。
{
"bot_id": "98174e8d635471c383b9ec7b",
"bot_name": "INDUSTRY DEMO (Travel) - SunCo",
"conversation_id": "67bc4129-6609-4v67-869d-db1d0186d1d8",
"platform_conversation_id": "57459bd72555b8452378f693",
"conversation_start_time": "2024-05-03T08:10:01.211+00:00",
"conversation_end_time": "2024-05-03T08:10:25.744+00:00",
"language": "eng",
"channel": "chat",
"labels": [
"web",
"API:getBookingDetails-Success"
],
"conversations_data": {
"bsatScore" : 5,
"convoId": "552cd72556e8452378d344",
"email": null,
"location": null,
"confidence_score": 95,
"lastDetectedLanguage": "eng",
"lastDetectedSentiment": "neutral",
"usedLanguage": "eng",
"channel": "web",
"bookingNo": null,
"booking":
[{
"country": "Spain",
"url": "https://cdn.pixabay.com/photo/2015/05/05/01/10/house-753270__340.jpg",
"location": "41.3485806,1.9787689",
"city": "Barcelona",
"numOfGuests": 4,
"days": 4,
"arrivalDate": "12-12-2022"
}],
"city": "Barcelona",
"manageBooking": "possible"
},
"test_mode": false,
"conversation_status": "botHandled",
"last_resolution": "resolved"
"triggered_replies": [
{
"reply_timestamp": "2024-05-03T08:10:02.991+00:00",
"reply_id": "53628e8e55b4f2459bcb2e72",
"reply_language": "eng",
"reply_name": "Greeting",
"reply_type": "normal",
"intent_id": "64628b8e55e4f2459bcb2e68"
},
{
"reply_timestamp": "2024-05-03T08:10:03.355+00:00",
"reply_id": "64628e8e55e4f2459bcb2f4b",
"reply_language": "eng",
"reply_name": "Welcome reply",
"reply_type": "welcome"
},
{
"reply_timestamp": "2024-05-03T08:10:12.951+00:00",
"reply_id": "2475e571f88f9c35af3ff45e",
"reply_language": "eng",
"reply_name": "Office or store location and opening hours",
"reply_type": "normal",
"intent_id": "6385e571f88f9c35af3ff46e"
}
],
"triggered_intent_replies": [
{
"intent_timestamp": "2024-05-03T08:10:02.991+00:00",
"intent_id": "53628e8e55b4f2459bcb2e72",
"intent_name": "Greeting",
"not_meaningful": true
},
{
"intent_timestamp": "2024-05-03T08:10:12.951+00:00",
"intent_id": "6375b571f88f9c35af3ff44e",
"intent_name": "Find location of rental",
"not_meaningful": false
}
],
"is_llm_conversation": false,
"bot_messages_count": "7",
"customer_messages_count": "4",
"not_understood_messages_count": "0"
}
よく使われるメトリック
おめでとうございます！AIエージェントの会話データが正常にエクスポートされました。エクスポートしたファイルのデータ探索を開始するための提案をいくつかご紹介します。
AIエージェントのメトリック
SELECT
--Total conversations
count(distinct conversation_id) total_conversations,
--AI agent handled rate
count(distinct case when conversation_status = 'botHandled' then conversation_id end) bot_handled_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate,
--Deflection rate
count(distinct case when conversation_status not in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) deflection_rate,
--Escalation rate
count(distinct case when conversation_status in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) escalation_rate,
--Failed escalation rate
count(distinct case when conversation_status = 'failedEscalation' then conversation_id end)/count(distinct conversation_id) failed_escalation_rate,
--Message understood rate
(sum(customer_messages_count)-sum(not_understood_messages_count
))/sum(customer_messages_count) messages_understood_rate
FROM TABLE
会話の最初の目的/最後の目的
select
distinct conversation_id,
triggered_use_cases[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE
FAQ
-
エクスポートした元ファイルが変更されることはありませんか？それとも時間が経つと変更され、再同期が必要になりますか？
エクスポートの元ファイルは変更されることはないので、再インポートする必要はありません。これにより、BIパイプラインにおけるエラー発生率が低減されます。 -
特定の日付でエクスポートされた会話数とAIエージェントの概要分析による会話数に違いがあります。原因は何でしょうか？
特定の日付のエクスポートデータに含まれるのは、その日に終了した会話のデータのみです。一方で、AIエージェントによる概要の分析にはステータスに関係なく、すべての会話が含まれます。このような仕様になっているのは、エクスポートファイルを変更不可に保つことや、重複データの発生を防ぐことなど、いくつかの理由によるものです。 -
では、AIエージェントの概要とエクスポートファイルの数値を一致させるにはどうすればよいのでしょうか？
特定の日付 X に発生したすべての会話を正確に把握するには、X 日とその翌日（X+1 日）のファイルを取り込むことで対応できます。こうすることで、たとえ会話が翌日にまたがっていた場合でも、日付 X のすべての会話を正確にカウントできます。 -
特定の日付でエクスポートされた会話の数と会話ログの会話数に違いがあります。原因は何でしょうか？
特定の日のエクスポートデータには、その日に終了した会話のデータのみが含まれます。一方、会話ログには、ステータスに関係なくすべての会話が含まれており、これはリアルタイムのデバッグを可能にするための仕様です。 -
会話には、その中でトリガされたすべての返信の情報が含まれますか？それが前日に発生したものであっても含まれるのでしょうか？
はい。ファイルに会話が含まれている場合、前日に発生した会話であっても、すべてのデータが含まれます。 -
提案エンジンの一環として行われたAIエージェントとの会話は、エクスポートに含まれるのでしょうか？
はい。AIエージェントの概要ダッシュボードではこれらの会話は除外されていますが、エクスポートデータには含まれます。AIエージェントの概要ダッシュボードと一致させるには、「bot_messages_count > 0」でフィルタリングしてください。