分析と利用状況

ⓘ

この機能をご利用いただける方

Pro または Plus の admin が呼び出し用の API キーを作成できます。GET /intents は conversations:read、それ以外のすべてのルートは analytics:read が必要です。スコープのない旧キーは拒否されます。
chat-to-sale のレポートはストアのプランに従い、下位プランでは一部のフィールドが除外されます。chat-to-sale のプラン制限を参照してください。

すべてのルートは Public API base URL への GET で、ボディは不要です。各リクエストに X-Api-Key を付けてください。読み取り専用のため、API からプランや請求を変更することはできません。

パス	返す内容
`/analytics/overview`	会話の合計、AI 回答率、AI 返信の評価、FAQ の閲覧数
`/analytics/ai`	AI 回答率、AI の関与、回答トピック
`/analytics/conversations`	会話の合計、応答時間、チームのパフォーマンス、チャネル別の合計
`/analytics/sales`	Chatty 経由の注文、chat-to-sale 率、ストア全体の売上
`/analytics/customer-intents`	お客様の問い合わせ内容(intent とフェーズ別)
`/analytics/satisfaction`	満足度アンケートの結果
`/analytics/handling`	担当者の対応時間と解決時間
`/analytics/campaigns/{id}`	1 つのキャンペーンのトリガー、インタラクション、カート追加イベント
`/analytics/chat-to-sale` と 8 つのサブビュー	chat-to-sale のファネル、売上、担当者、解決
`/intents`	ストアで有効な intent ラベル
`/subscription`	現在のプランと AI 返信の上限
`/subscription/usage`	現在のサイクルの利用状況と請求履歴

日付の範囲を選ぶ

すべての /analytics/* ルートで同じ範囲指定を使えます。

パラメーター	意味
`from`, `to`	両端を含む日付(`YYYY-MM-DD`)。両方を指定するか、どちらも指定しません。`range` より優先されます。
`range`	`today`、`yesterday`、`last-3-days`、`last-7-days`、`last-30-days`(デフォルト)、`last-3-months`、`this-month`、`last-month`

範囲は 1〜90 日です。これより長い範囲や、to が from より前の場合は 400 VALIDATION_FAILED を返します。
日付はストアのタイムゾーンで数え、未設定の場合は UTC を使います。
どのレポートも、直前の期間(同じ日数、this-month と last-month では前月)との比較を含みます。
金額はストアの通貨です。分析のレスポンスに通貨コードは含まれません。

curl 'https://app.chatty.net/v1/analytics/overview?from=2026-10-01&to=2026-10-21' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

レスポンスの形式

分析ルートは {"success":true,"data":{...}} を返します。data.updatedAt はレポートを集計した時刻です。レポートは最長 1 時間キャッシュされるため、新しい会話が反映されるまで最大でその時間かかります。

ステータスだけでなく success も確認してください。 レポートの作成中に想定外の失敗が起きると、HTTP 200 で {"success":false,"error":"..."} を返します。検証エラーや参照エラーは通常どおり error.code を使います。

/subscription、/subscription/usage、/intents は success や updatedAt を含まない {"data":...} を返し、キャッシュされません。

Overview、AI、conversations、sales

この 4 つのレポートでは、各数値を {current, previous, unit, description} の形式で返します。previous は比較期間の値です。window オブジェクトも返します。

{
  "success": true,
  "data": {
    "window": {
      "from": "2026-09-24T14:22:00.000Z",
      "to": "2026-10-22T14:22:00.000Z",
      "timeZone": "America/New_York",
      "unit": "UTC instants for calendar dates in the shop time zone",
      "description": "The time window applied to every analytics value in this response."
    },
    "conversations": {
      "current": {"resolutionRate": 0.82, "totalConversations": 410, "totalHumanConversations": 150, "totalHumanResolvedConversations": 120},
      "previous": {"resolutionRate": 0.8, "totalConversations": 380},
      "unit": "conversations and percent",
      "description": "Conversation totals and resolution rate for the requested time window."
    },
    "aiAnswerRate": {
      "current": {"totalCount": 900, "successCount": 760, "successRate": 0.8444},
      "previous": {"totalCount": 850, "successCount": 700, "successRate": 0.8235},
      "unit": "answers and proportion from 0 to 1",
      "description": "AI knowledge-answer attempts, successful answers, and answer rate for the requested time window."
    },
    "updatedAt": "2026-10-22T14:22:05.123Z"
  }
}

この例は /analytics/overview の抜粋で、実際には satisfaction と faqViews も返します。チャート用の配列は省略しています。

ルート	数値
`/analytics/overview`	`conversations`、`aiAnswerRate`、`satisfaction`、`faqViews`
`/analytics/ai`	`answerRate`、`involvement`、`topics`
`/analytics/conversations`	`overview`、`responseTime`、`teamPerformance`、`byChannel`
`/analytics/sales`	`attributedOrders`、`chatToSale`、`storeSales`

resolutionRate と successRate は 0〜1 の割合です。teamPerformance.value[].resolvedRate は 0〜100 の整数のパーセントです。
overview の satisfaction はアンケートの回答ではなく、AI 返信の評価(great、good、bad)を集計します。アンケートの結果は /analytics/satisfaction にあります。
topics.value は AI の回答トピックを多い順に並べ、total と rate を含みます。
byChannel のキーは online store、email、facebook、instagram、whatsapp です。
attributedOrders は Chatty が支援した注文数です。storeSales はストアのすべての注文を対象にします。

Customer intents

/analytics/customer-intents は、お客様のメッセージから Chatty が検出した intent を報告します。任意のフィルターは、いずれもカンマ区切りのリストです。

パラメーター	値
`phases`	`pre`、`purchase`、`post`、`cross`、`junk`、`customer_type`、`none`
`intents`	`GET /intents` で取得する intent の slug。不明な slug は無視されます。

{
  "success": true,
  "data": {
    "rows": [{"slug": "product_info", "name": "Product information", "phase": "pre", "total": 120, "compareTotal": 100, "percentage": 24.5}],
    "junkRows": [{"slug": "marketing_spam", "name": "Marketing spam", "total": 8, "compareTotal": 5, "percentage": 1.6}],
    "phases": [{"phase": "pre", "total": 300, "compareTotal": 280, "messages": 250, "compareMessages": 240}],
    "labelledMessages": 490,
    "compareLabelledMessages": 450,
    "noneMessages": 60,
    "compareNoneMessages": 55,
    "requestMessages": 480,
    "compareRequestMessages": 440,
    "updatedAt": "2026-10-22T14:22:05.123Z"
  }
}

rows は intent を多い順に並べ、junk の intent は junkRows に入ります。percentage はラベル付きメッセージに占める割合で、小数第 1 位までです。compare で始まるフィールドは比較期間の値です。

GET /intents はストアで有効な intent ラベルを返すので、slug に対応する名前を表示できます。

{"data":[{"slug":"product_info","name":"Product information","phase":"pre"},{"slug":"order_status","name":"Order status","phase":"post"}]}

Satisfaction、handling、campaigns

これらのレポートは、指定した期間の sourceData と、比較期間の compareData を返します。

ルート	フィールド
`/analytics/satisfaction`	`satisfiedCount`(評価 4 または 5)、`submittedCount`、`surveyCount`、`ratedSurveyCount`、`totalPoints`、`ratingCounts`(評価 1〜5 の件数)
`/analytics/handling`	`avgAgentHandlingTime`、`avgResolutionTime`、および指定した期間のチャートデータ
`/analytics/campaigns/{id}`	`triggered`、`interacted`、`add_to_cart`(常に含まれます)

{"success":true,"data":{"sourceData":{"triggered":120,"interacted":30,"add_to_cart":7},"compareData":{"triggered":100,"interacted":25,"add_to_cart":4},"updatedAt":"2026-10-22T14:22:05.123Z"}}

別のストアのキャンペーン ID を指定すると、404 NOT_FOUND と Campaign not found を返します。API で満足度を読み取っても、admin 上でアンケート結果が既読になることはありません。

Chat-to-sale

パス	返す内容
`/analytics/chat-to-sale`	主要な数値。`/kpi` と同じデータ
`/analytics/chat-to-sale/kpi`	会話、コンバージョンした会話、注文、売上、解決、満足度、ストア全体の合計
`/analytics/chat-to-sale/sales`	ステージ別・トピック別のファネル、チャート、売れ筋商品
`/analytics/chat-to-sale/sales/spark`	同じ長さの直近 4 期間のファネル(古い順)
`/analytics/chat-to-sale/agents`	チームメンバーごとのチャット数と売上
`/analytics/chat-to-sale/resolution`	解決方法別の会話
`/analytics/chat-to-sale/agent-table`	メンバーごとの注文、解決率、初回応答時間
`/analytics/chat-to-sale/phase-mix`	メンバーごとの会話を購入前・購入・購入後に分けた内訳
`/analytics/chat-to-sale/topics`	各メンバーの上位 2 つのトピック

多くの数値は ai、human、both に分かれます。ai は AI だけが回答したもの、human はチームメンバーが返信したものです。both は重複を除いた合計なので、ai と human の和は both より小さくなることがあります。削除済みの会話とスパムは除外されます。

{
  "success": true,
  "data": {
    "current": {
      "extensives": {
        "conversations": {"ai": 200, "human": 150, "both": 410},
        "converted": {"ai": 12, "human": 8, "both": 20},
        "orders": {"ai": 13, "human": 9, "both": 22},
        "revenue": {"ai": 900.0, "human": 640.5, "both": 1540.5}
      },
      "resolution": {"auto": 180, "manual": 120},
      "csat": {"satisfied": {"ai": 30, "human": 20, "both": 50}, "submitted": {"ai": 40, "human": 30, "both": 70}},
      "storeRevenue": 15400.0,
      "storeOrders": 220
    },
    "compare": {},
    "updatedAt": "2026-10-22T14:22:05.123Z"
  }
}

この例は /kpi の抜粋です。compare には、比較期間について同じキーが入ります。storeRevenue と storeOrders はストアのすべての注文が対象です。

/sales のファネルの各ステージは累積です。Pre はすべての会話、Purchase は支援した注文があるもの、Post は発送済みの注文があるものです。返金は売上から差し引かれます。チャートは 1 日の範囲では時間単位、それ以外は日単位です。
/resolution は 5 つの状態を aiResolved、agentResolved、mixResolved、notReplyResolved、open の順に返し、それぞれ count と 0〜1 の share を含みます。
/agents は、最後に割り当てられたメンバーに売上を計上します。すでにストアにいないメンバーは含まれません。
/agent-table はメンバーをチャット数順に並べます。frt は初回応答時間の中央値で、null はそのメンバーが一度も返信していないことを表します。

chat-to-sale のプラン制限

Chatty は、ストアのプランに含まれないフィールドを取り除きます。エラーにはならず、フィールドが存在しないか空になります。/kpi、/agents、/resolution、/phase-mix は制限されません。

プラン	除外される内容
Free	Basic で挙げたものすべてに加え、`/sales` と `/sales/spark` の `Purchase` と `Post` ステージにある `orders` と `revenue`
Basic	トピックの詳細(トピックには `volume` のみ残ります)、`topicProducts`、`topProducts` の商品価格と売上、`/agent-table` の運用に関する数値、`/topics` のすべて(`{"agents":[]}`)
Pro、Plus	なし

アップグレードは、キャッシュ済みのレポートも含め、次のリクエストから反映されます。

サブスクリプションと利用状況

{
  "data": {
    "plan": {"id": "pro", "name": "Pro", "interval": "monthly", "isOnTrial": false, "trialEndsAt": null},
    "aiQuota": {"used": 420, "limit": 1000, "remaining": 580, "unit": "AI replies in the current billing cycle"}
  }
}

GET /subscription は、プランと現在の請求サイクルの AI 返信の上限を返します。remaining は 0 を下回りません。GET /subscription/usage は currentCycle(startsAt、used、limit、bonusUsed、bonusLimit)と history.value を返します。history.value は請求期間ごとに 1 行で、periodStart、periodEnd、plan、used、limit、amount、currency を含みます。値がない項目は null です。どちらの例も抜粋です。

エラー

HTTP	コード	意味
`200`	`success: false`	レポートの作成に失敗しました。時間をおいて再試行してください。
`400`	`VALIDATION_FAILED`	`from` / `to` の片方だけの指定、不明な `range`、1〜90 日を外れた範囲、または無効な日付です。
`400`	`INVALID_API_VERSION`	`X-Api-Version` の日付が無効です。
`401`	`UNAUTHENTICATED` / `INVALID_API_KEY`	キーがない、不明、または失効しています。
`403`	`FORBIDDEN`	スコープがない、または旧キーです。
`404`	`NOT_FOUND`	ストアまたはキャンペーンが見つかりません。
`429`	`RATE_LIMITED`	Public API 共通の上限に達しました。

MCP では、get_shop_analytics が API キーまたは OAuth で intent、満足度、キャンペーン、handling、chat-to-sale のレポートを読み取り、同じプラン制限が適用されます。list_intents は API キーで intent ラベルを読み取ります。get_analytics_overview や get_subscription などの従来のツールは、それ以外のルートを読み取ります。MCP ツールリファレンスを参照してください。

Shortcuts and Campaigns Channels and Integrations