高度なAIエージェント用データのエクスポートAPIの使用

現在のプランを確認

アドオン	AIエージェント - Advanced

Data Export APIは、AIエージェントの可能性を最大限に引き出すための鍵として機能し、会話データをエクスポートし、さまざまなプラットフォームやアプリケーション間で統合できるようになります。あなたが開発者、ビジネスアナリスト、ITプロフェッショナルのいずれの場合も、Zendesk APIは価値あるインサイトと会話のMetadataを抽出する合理化された安全なソリューションを提供することで、イノベーションの推進、情報に基づく意思決定、組織の新たな高みへの推進を可能にします。

この記事では、データのエクスポートAPIの使用方法と出力について説明します。

組織IDを取得する

このステップを実行できるのは、管理者ロールを持つユーザーだけです

1. ユーザー管理 -> 組織管理に移動する 
2. 組織のプロフィールを開く
3. 所属する組織IDはURLに入っています

   https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s

APIトークンを生成する

トークンの生成は管理者ロールを持つユーザーのみが行うことができます

1. ユーザー管理 -> 組織管理に移動する 
2. 組織のプロフィールを開く
3. 左メニューのAPIキーに移動
4. 生成をクリックし、保存ボタンをクリックする
5. キーをコピーして安全に保管する

組織管理ページを終了すると、トークンにアクセスできなくなります。以前に生成したトークンを紛失した場合も、再生成ボタンをクリックするだけでトークンを取り消すことができます。古いトークンの有効性は取り消され、新しく生成されたトークンを使用できます。

 

APIについて

POST - https://api.ultimate.ai/data-export/v2/get-signed-urls

ヘッダー

name	必須	type
botId	true	string
organizationId	true	string
authorization	true	string

本文

name	必須	type
date	true	ISO date string

レスポンス

HTTPコード	レスポンス
200	{ "date": "string", "urls": [ "string" ] }
401	アクセス権がありません
500	内部サーバーエラー

 

メモ:

• ファイルへのURLは、リクエスト日から1日後に有効期限が切れます。有効なリンクを取得するには、もう一度APIコールを実行します。
• 現在の日付から30日以内の日付のデータをリクエストできます。それ以前のデータは履歴データと見なされ、さまざまな準備が必要になります。
  
  • 例：現在の日付が2024年4月15日の場合、リクエストの日付は2024年3月16日から2024年4月15日までの任意の日付になります。

ファイルスキーマ

APIの出力は、以下で概説する構造に従って、所定の日のすべての会話を含むJSONドキュメントです。

• このファイルは、各オブジェクトが会話であるJSONオブジェクトのリストです
• ファイルの名前はconversation_bot-id_date_000000000000.jsonになります

プロパティ	説明	タイプ
"bot_id"	ボットの一意のID	"bot_id": { "type": "string" },
"bot_name"	ボットの名前	"bot_name": { "type": "string" },
"conversation_id"	生成された会話ID	"conversation_id": { "type": "string" },
"platform_conversation_id"	CRM固有のID	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	UTCタイムゾーンに基づいて会話が開始された日付と時刻	"conversation_start_time": { "type": "string" },
"conversation_end_time"	UTCタイムゾーンに基づいて会話が終了した日付と時刻	"conversation_end_time": { "type": "string" },
"language"	会話の言語	"language": { "type": "string" },
"channel"	会話のチャネル。チャットまたはチケットのいずれか	"channel": { "type": "string" },
"labels"	会話に関連付けられているすべてのラベルのリスト	"labels": { "type": "array", "items": { "type": "string" } },
"conversations_data"	セッションパラメータは会話に関連付けられます。これは、値を持っていたパラメータのキーのリストです。未定義のキーはこのリストに含まれません メモ: 文字列として格納されていても、「conversations_data」には別のJSONオブジェクトが含まれる BSATスコアは、会話データオブジェクトで提供される BSATスコアの値 -1 = ユーザーがBSATを提案されたが、応答しなかった NULL ＝ ユーザーはBSATを提供されなかった 例： "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	会話がテスト会話であるかどうかを識別するフラグ	"test_mode": { "type": "boolean" },
"conversation_status"	会話の解決例：bot_handled	"conversation_status": { "type": "string" },
"last_resolution"	会話の最終解決。通知、解決、エスカレーション、または未定義のいずれかになります。	"last_resolution": { "type": "string" },
"triggered_replies"		"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_intent_replies"	目的ベースの返信	"triggered_intent_replies": { "type": "array", "items": { "type": "string" } },
"is_llm_conversation"	会話がLLM会話であるかどうかを識別するフラグ（少なくとも1つのLLM回答がある）	"is_llm_conversation": { "type": "boolean" },
"llm_notUnderstood_count"	LLM会話内の理解されていないメッセージの数	"llm_notUnderstood_count": { "type": "string" },
"llm_responseGenerated_count"	LLM会話内の応答生成メッセージ数	"llm_responseGenerated_count": { "type": "string" },
"llm_errorOccurred_count"	LLM会話で発生したエラーメッセージの数	"llm_errorOccurred_count": { "type": "string" },
"llm_escalationRequired_count"	LLM会話内のエスカレーション必須メッセージ数	"llm_escalationRequired_count": { "type": "string" },
"llm_fallback_count"	LLM会話内のフォールバックメッセージ数	"llm_fallback_count": { "type": "string" },
"bot_messages_count"	AIエージェントメッセージ数	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	訪問者のメッセージ数	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	一般に理解されていないメッセージ数	"not_understood_messages_count": { "type": "string" },

応答例

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",
  "visitor_messages_count": "4",
  "not_understood_messages_count": "0"
}

よく使用されるメトリック

おめでとうございます！AIエージェントの会話データが正常にエクスポートされました。以下では、エクスポートされたファイルのデータ探索を開始するための提案をいくつか紹介します。

AIエージェントメトリック

SELECT
--Total conversations
count(distinct conversation_id) total_conversations,

--Bot 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,

--Informed rate
count(distinct case when last_resolution = 'informed' then conversation_id end)/count(distinct conversation_id) informed_rate,

--Custom resolution rate
count(distinct case when last_resolution in ('informed', 'resolved') then conversation_id end)/count(distinct conversation_id) automation_rate,

--Message understood rate
(sum(visitor_messages_count)-sum(not_understood_messages_count
))/sum(visitor_messages_count) messages_understood_rate

FROM TABLE

会話の最初の目的/最後の目的

select 
distinct conversation_id,
triggered_intent_replies[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE

最初の意味のある（またはフィルタリングされた）目的別のメトリック

with meaningful_intents as (
select conversation_id, first_meaningful_intent, conversation_status from 
(
select distinct conversation_id,
intent.intent_name first_meaningful_intent,
conversation_status,
--order by ascending intent_timestamp for last intent
ROW_NUMBER() OVER (PARTITION BY conversation_id order by intent.intent_timestamp asc) rn,
FROM TABLE
LEFT JOIN UNNEST(triggered_intent_replies) intent
--select only intents that are labeled as meaningful
where intent.not_meaningful is false 
--filter for specific intents
and intent.intent_name not in ('Greeting', 'Talk to a human/agent')
)
where rn=1
)

--calculate metrics for each intent
select first_meaningful_intent,
count(distinct conversation_id) total_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate
from meaningful_intents
group by first_meaningful_intent
order by total_conversations desc

FAQ

• エクスポートされたファイルは不変か、それとも時間の経過とともに変更され、再同期が必要か。
  エクスポートされたファイルは不変であるため、再インポートする必要がなく、BIパイプラインでエラーが発生しにくくなります。
• エクスポートされた会話とAIエージェント要約分析とでは、特定の日付の会話数に違いがあります。どのような理由が考えられますか?
  特定の日付のエクスポートデータには、その日に終了した会話のデータのみが含まれます。これは、任意の状態の会話が含まれるAIエージェント概要分析とは異なるアプローチです。これには、エクスポートファイルの不変性とデータの重複防止など、複数の理由があります。
• では、AIエージェント概要でレポートされた数値とエクスポートされたファイルを同等にするにはどうすればよいですか。
  特定日xに行われたすべての会話の全体像を把握するための操作は、日xと日x+1に生成されたファイルを取り込むだけです。これら2つの日付のファイルを取り込むことで、たとえ翌日以降に会話が中断したとしても、日付xのすべての会話をカウントすることができます。
• エクスポートされた会話と会話ログとで、特定の日付の会話数に違いがあります。どのような理由が考えられますか?
  特定の日付のエクスポートデータには、その日に終了した会話のデータのみが含まれることに注意してください。これは、会話ログのどのステータスの会話も含め、リアルタイムのデバッグを可能にする方法とは異なります。
• 会話には、それらの返信が前日であっても、会話でトリガされたすべての返信に関する情報が含まれていますか？
  はい。会話がファイルに含まれている場合、会話が前日のものであっても、その会話のすべてのデータが含まれます。
• 仮想エージェントには提案エンジンの一部として会話が入っていますが、それらの会話はエクスポートに表示されますか？
  はい。AIエージェント概要ダッシュボードでは除外されますが、エクスポートされたデータでは引き続き使用できます。これらを除外し、AIエージェント概要ダッシュボードと同等にするには、「bot_messages_count > 0」でフィルタリングします。