logo
Development
概要開発スペースワークスペースAPI Referenceベストプラクティス更新履歴
検索
日本語
API Reference / アナリティクスAPI / Agent の有人対応への切り替え率を取得
Agent の有人対応への切り替え率を取得
最終更新日：14日前

Agent の有人対応への切り替え率を取得

時間区間ごとに特定のエージェントのセッション数、人手対応に転換したセッション数、及び転換率を取得します。計測基準はコンソールの「エージェントインサイト → 人手対応転換率」と一致します。

注意：最大で92日分のデータを取得可能です。開発スペースのチャネルのみを集計対象とし、統計範囲は下記「統計基準」を参照してください。

リクエスト方法

GET

呼び出し先

https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff

認証方法

アカウント単位の DevKey / DevSecret を使用した Basic 認証：Authorization: Basic ${BASIC_TOKEN}。${BASIC_TOKEN} は DevKey:DevSecret の Base64 エンコードです。

  • 呼び出すアカウントは org_id に対応する組織のメンバーであり、「使用量閲覧」権限を持っている必要があります（組織 Owner、管理者はデフォルトで権限あり）、かつ該当エージェントを閲覧できる必要があります：エージェントの作成者、組織 Owner、または該当エージェント（または全エージェント）の権限を付与されたメンバー。
  • 組織の所在するデータセンターのアドレスを使用してください。${endpoint} は 組織リストの照会 で返された region（SG → sg、TH → th、JP → jp）を取得します。他のデータセンターを呼び出すと「その組織のメンバーではありません」と返されます。

呼び出し頻度

  • 開発者キーごとに本インターフェースは1分間に最大60回呼び出すことができます。
  • 各呼び出しは組織プランの「統計系 API」1分間の使用枠に同時にカウントされ、Agent API Key による統計系インターフェース呼び出しと共通の枠を使用します。
  • クエリ結果は10分間キャッシュされます。1時間に1回の呼び出しを推奨します。

リクエスト

リクエスト例

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff?org_id=${org_id}&agent_id=${agent_id}&start_time=1788192000000&end_time=1790784000000' \ -H 'Authorization: Basic ${BASIC_TOKEN}'
                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/agent/stat/human-handoff?org_id=${org_id}&agent_id=${agent_id}&start_time=1788192000000&end_time=1790784000000' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'
このコードブロックをポップアップで表示

リクエストヘッダー

フィールド タイプ 説明
Authorization Basic ${BASIC_TOKEN} DevKey:DevSecret を Base64 エンコードした後の Basic トークンを使用します。

リクエストパラメータ

フィールド タイプ 必須 説明
org_id String はい 組織の ID。
agent_id String はい エージェント ID。Workflow はサポートされません。
start_time Long はい 開始時間、ミリ秒のタイムスタンプ。組織のタイムゾーンで当日 0 時に拡張します。
end_time Long はい 終了時間（含まず）、ミリ秒のタイムスタンプ。組織のタイムゾーンで前のミリ秒の日付を最後の日として取得します。開始日と終了日は最大で 92 日間です。

レスポンス

レスポンス例

{ "code": 0, "message": "OK", "data": { "agent_id": "65f0c2a1b4e8d93a1c7e5b21", "timezone": "+08:00", "range_start_date": "2026-09-01", "range_end_date": "2026-09-29", "data_until": 1790665200000, "conversation_count": 1200, "handoff_conversation_count": 96, "handoff_rate": 0.0800 } }
                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "agent_id": "65f0c2a1b4e8d93a1c7e5b21",
        "timezone": "+08:00",
        "range_start_date": "2026-09-01",
        "range_end_date": "2026-09-29",
        "data_until": 1790665200000,
        "conversation_count": 1200,
        "handoff_conversation_count": 96,
        "handoff_rate": 0.0800
    }
}
このコードブロックをポップアップで表示

成功した対応

フィールド タイプ 説明
agent_id String 銀のエディ。
timezone String タイムゾーン(UTCオフセット、例:+08:00)を整理し、日付をどのタイムゾーンに分けているかを指定します。
range_start_date String 実際の統計yyyy-MM-dd開始日(組織のタイムゾーンを含む)。
range_end_date String 実際の統計yyyy-MM-dd終了日(組織のタイムゾーンを含む)。
data_until Long データカウントのモーメント(ミリ秒タイムスタンプ):区間にリアルタイム計算日が含まれている場合、計算時間のリアルタイム部分(結果は最大10分までキャッシュ)が含まれる。 区間全体が日次統計を完了すると、区間エンドクレジットがエンドクレジットとなります。
conversation_count Long インターバル内の会話数(1日の累積)。
handoff_conversation_count Long その中で、人間のエージェントに転送されるセッション数は
handoff_rate Number 換算率 = handoff_conversation_count ÷ conversation_count、0から1、小数点以下4桁まで四捨五入; セッション数が0の場合、null。

失敗対応

フィールド タイプ 説明
code Integer エラーコード。
message String エラー詳細。

エラーコード

HTTPステータスコードはエラーコードの最初の3ビットで、例えば40000は4000、401は40100、403は403132です。

エラーコード 説明
40000 必要なパラメータの欠落や無効なパラメータなどのパラメータエラー。
40001 呼び出しが多すぎます：この開発者キーはこのインターフェースの毎分上限を超えています。
40008 組織プラン「統計API」の毎分割当を超えました。
40010 インターフェースは一時的に閉鎖されています。後でもう一度お試しください。
40100 権限がありません：利用状況を確認する権限がないか、またはこのエージェントを閲覧する権限がありません（エージェントが組織に属していない場合を含む）。
40105 組織のメンバーではないか、他のデータセンターのアドレスに呼び出しました。
40324 DevKey または DevSecret が間違っています。
40378 エージェントは削除されました。
403132 時間範囲が無効です：開始時間が終了時間以前でないか、最大検索範囲を超えています。

統計基準

  • セッション数：1日ごとに会話のあったセッション数を日ごとに累計します。日を跨いで続く会話のセッションは各日の分をそれぞれカウントします。
  • 人への転送セッション数：そのうち人に転送されたセッション数。
  • 統計範囲：開発スペースのチャネルのみ統計対象とします。API、共有ページ、ウェブ埋め込み、バブルコンポーネント、LiveDesk、各種インスタントメッセージおよび電話チャネルを含みます。エージェントがワークスペースに公開された後、ワークスペース内で使用された場合は含まれません。
  • 更新頻度：既に完了した日の統計については日次統計を参照します。当日はリアルタイムで計算されます。日次統計は組織のタイムゾーンの0時以降、統計タスクによって生成され、生成完了前は前日もリアルタイム計算に基づき、0時以降に「昨日」が0になることはありません。
  • リアルタイム部分の基準：セッションの最後の会話時間に基づいてカウントします。日を跨いで続く会話のセッションはリアルタイム部分では1回のみカウント（最後の会話の日にカウント）され、日ごとの累計統計とは若干異なる場合があります。