数据分析 API

概述

数据分析 API 提供会话量、满意度、热门问题、渠道分布等多维度数据，帮助运营团队量化 AI 客服效果，发现改进方向。

获取会话统计

GET /api/kf/analytics/conversations?start_date=2025-01-01&end_date=2025-01-31&granularity=day
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

查询参数：

• start_date / end_date（必填）：日期范围，格式 YYYY-MM-DD
• granularity：day / week / month
• channel（可选）：按渠道筛选

响应示例：

{
  "code": 0,
  "data": {
    "total_conversations": 3842,
    "avg_daily": 124,
    "ai_resolved": 3156,
    "ai_resolved_rate": 0.821,
    "transferred_to_human": 486,
    "transfer_rate": 0.127,
    "avg_response_time_ms": 320,
    "daily_breakdown": [
      { "date": "2025-01-01", "conversations": 98, "ai_resolved": 82 },
      { "date": "2025-01-02", "conversations": 115, "ai_resolved": 95 }
    ]
  }
}

获取满意度数据

GET /api/kf/analytics/satisfaction?start_date=2025-01-01&end_date=2025-01-31
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

{
  "code": 0,
  "data": {
    "total_ratings": 2180,
    "rating_rate": 0.567,
    "avg_score": 4.32,
    "distribution": {
      "5_star": 1240,
      "4_star": 586,
      "3_star": 210,
      "2_star": 98,
      "1_star": 46
    },
    "by_channel": [
      { "channel": "web_widget", "avg_score": 4.5, "count": 1420 },
      { "channel": "wechat", "avg_score": 4.1, "count": 760 }
    ]
  }
}

获取热门问题排行

GET /api/kf/analytics/top-questions?period=7d&limit=20
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

{
  "code": 0,
  "data": [
    { "question": "如何修改收货地址", "count": 342, "ai_resolved_rate": 0.91 },
    { "question": "订单多久能到", "count": 286, "ai_resolved_rate": 0.88 },
    { "question": "支持哪些支付方式", "count": 215, "ai_resolved_rate": 0.95 }
  ]
}

渠道分析

GET /api/kf/analytics/channels?start_date=2025-01-01&end_date=2025-01-31
Authorization: Bearer {access_token}
X-Tenant-Id: {tenant_id}

{
  "code": 0,
  "data": {
    "channels": [
      {
        "name": "网页客服",
        "conversations": 2100,
        "unique_users": 1580,
        "avg_session_duration_sec": 185,
        "ai_resolved_rate": 0.84
      },
      {
        "name": "微信公众号",
        "conversations": 1200,
        "unique_users": 890,
        "avg_session_duration_sec": 142,
        "ai_resolved_rate": 0.78
      },
      {
        "name": "邮件",
        "conversations": 542,
        "unique_users": 480,
        "avg_session_duration_sec": 320,
        "ai_resolved_rate": 0.72
      }
    ]
  }
}

📊 最佳实践：建议每天定时调用会话统计 API，将数据同步到内部 BI 系统。使用 granularity=day 可以追踪日趋势变化。