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/v2/get-signed-urls
米国用のAPI：POST - https://api.us.ultimate.ai/data-export/v2/get-signed-urls
ヘッダー
|
名前 |
必須 |
タイプ |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
本文
|
名前 |
必須 |
タイプ |
|---|---|---|
|
|
|
|
レスポンス
|
HTTPコード |
レスポンス |
|---|---|
|
200 |
|
|
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": {
|
| "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": {
|
| "language" | 会話の使用言語 |
"language": {
|
| "channel" | 会話のチャネル。チャットまたはチケット |
"channel": {
|
| "labels" | 会話に関連付けられたラベルの全リスト |
"labels": {
|
| "conversations_data" |
会話に関連付けられたセッションパラメータ。パラメータに値を含むキーのリストです。未定義のキーはこのリストに含まれません。 メモ：
例： "conversations_data": {
|
"conversations_data": {
|
|
"test_mode"
|
会話がテスト会話かどうかを識別するフラグ |
"test_mode": {
|
| "conversation_status" | 会話の解決例：bot_handled |
"conversation_status": {
|
| "last_resolution" | 会話の最終的な解決内容。情報提供済み、解決済み、エスカレーション済み、または未定義。 |
"last_resolution": {
|
| "triggered_replies" |
"triggered_replies": {
|
|
| "triggered_intent_replies" |
目的ベースの返信 |
"triggered_intent_replies": {
|
| "is_llm_conversation" | 会話がLLM会話であるかどうかを識別するフラグ（少なくとも1つのLLM回答があること） |
"is_llm_conversation": {
|
| "llm_notUnderstood_count" | LLM会話で理解できなかったメッセージの数。 |
"llm_notUnderstood_count": {
|
| "llm_responseGenerated_count" | LLM会話で応答が生成されたメッセージの数。 |
"llm_responseGenerated_count": {
|
| "llm_errorOccurred_count" | LLM会話でエラーが発生したメッセージの数。 |
"llm_errorOccurred_count": {
|
| "llm_escalationRequired_count" | LLM会話でエスカレーションが必要になったメッセージの数。 |
"llm_escalationRequired_count": {
|
| "llm_fallback_count" | LLM会話でフォールバックされたメッセージの数。 |
"llm_fallback_count": {
|
| "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",
"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 日）のファイルを取り込むことで対応できます。こうすることで、たとえ会話が翌日にまたがっていた場合でも、日付 X のすべての会話を正確にカウントできます。 -
特定の日付でエクスポートされた会話の数と会話ログの会話数に違いがあります。原因は何でしょうか？
特定の日のエクスポートデータには、その日に終了した会話のデータのみが含まれます。一方、会話ログには、ステータスに関係なくすべての会話が含まれており、これはリアルタイムのデバッグを可能にするための仕様です。 -
会話には、その中でトリガされたすべての返信の情報が含まれますか？それが前日に発生したものであっても含まれるのでしょうか？
はい。ファイルに会話が含まれている場合、前日に発生した会話であっても、すべてのデータが含まれます。 -
提案エンジンの一環として行われたAIエージェントとの会話は、エクスポートに含まれるのでしょうか？
はい。AIエージェントの概要ダッシュボードではこれらの会話は除外されていますが、エクスポートデータには含まれます。AIエージェントの概要ダッシュボードと一致させるには、「bot_messages_count > 0」でフィルタリングしてください。