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)
按智能体和渠道每组返回一条记录,按会话数排序。
会话(type=chats)
逐条返回范围内的会话,从最早到最新,默认每页 100 条。只包含已结束的会话(有 ended_at):仍在进行中的会话要等结束后才会出现。
分页
只要next_cursor 不为 null,就使用相同参数并加上 cursor=<next_cursor> 请求下一页。会话按 created_at 和 id 排序,因此各页之间不会重复或遗漏。
错误
错误返回 JSON{ "success": false, "message": "…" }。
限制与最佳实践
- 每个请求最多 31 天,每页最多 100 个会话。
- 一个完整月份的
metrics请求需要几秒钟。月报或日报每个周期调用一次即可,无需循环查询。 - 导出整月会话时,请逐页依次获取,不要并行请求。
- 请妥善保管密钥并只在服务器端使用。不要在浏览器或移动应用中使用。
