跳转到主要内容
分析 API 是一个只读端点,返回贵公司的会话数据。它有两种模式:
  • type=metrics:按智能体和渠道汇总的数据(会话数、转人工、AI 自主处理率、通话时长、WhatsApp 通知、重复联系,以及按天和按小时的序列)。适用于报表和看板。
  • type=chats:每个会话一行,包含其全部参数,分页返回。适用于导出或核对原始数据。

🔑 认证

每个请求都需要一个具有 analytics_api 权限的 API 密钥。请在 Lovi 的个人资料中创建(个人资料 → API Key),并勾选 分析(API) 权限;它与网页小组件使用的密钥不同。 请在 x-api-key 请求头中发送密钥(推荐),或使用 URL 参数 access_key。
公司始终由密钥确定。密钥只能读取其所属公司的数据,没有任何参数可以选择其他公司。

端点

URL 参数

日期按 tz 解释:当 tz=Europe/Madrid 时,date_from=2026-10-01&date_to=2026-10-31 覆盖马德里时间 10 月 1 日 00:00 至 11 月 1 日 00:00。夏令时切换已自动处理。 响应中的所有时间均为 UTC(以 Z 结尾的 ISO 8601)。

指标(type=metrics)

按智能体和渠道每组返回一条记录,按会话数排序。
与上月对比:每月各调用一次端点,共调用两次,然后计算差值。 仅统计有人工坐席当天的自主处理率:使用 daily,只保留 escalated > 0 的日期。

会话(type=chats)

逐条返回范围内的会话,从最早到最新,默认每页 100 条。只包含已结束的会话(有 ended_at):仍在进行中的会话要等结束后才会出现。

分页

只要 next_cursor 不为 null,就使用相同参数并加上 cursor=<next_cursor> 请求下一页。会话按 created_at 和 id 排序,因此各页之间不会重复或遗漏。

错误

错误返回 JSON { "success": false, "message": "…" }。

限制与最佳实践

  • 每个请求最多 31 天,每页最多 100 个会话。
  • 一个完整月份的 metrics 请求需要几秒钟。月报或日报每个周期调用一次即可,无需循环查询。
  • 导出整月会话时,请逐页依次获取,不要并行请求。
  • 请妥善保管密钥并只在服务器端使用。不要在浏览器或移动应用中使用。