> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 分析 API

> 查询您的会话分析数据：按智能体和渠道汇总的指标，以及每个会话的详情

分析 API 是一个只读端点，返回贵公司的会话数据。它有两种模式：

* **`type=metrics`**：按智能体和渠道汇总的数据（会话数、转人工、AI 自主处理率、通话时长、WhatsApp 通知、重复联系，以及按天和按小时的序列）。适用于报表和看板。
* **`type=chats`**：每个会话一行，包含其全部参数，分页返回。适用于导出或核对原始数据。

## 🔑 认证

每个请求都需要一个具有 **`analytics_api`** 权限的 API 密钥。请在 Lovi 的个人资料中创建（**个人资料 → API Key**），并勾选 **分析（API）** 权限；它与网页小组件使用的密钥不同。

请在 `x-api-key` 请求头中发送密钥（推荐），或使用 URL 参数 `access_key`。

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=metrics&date_from=2026-10-01&date_to=2026-10-31"
```

> [!NOTE]
>
> 公司始终由密钥确定。密钥只能读取其所属公司的数据，没有任何参数可以选择其他公司。

## 端点

```
GET https://cloud.lovi.ai/functions/v1/analytics
```

### URL 参数

| 参数 | 必填 | 说明 |
| - | - | - |
| `type` | 是 | `metrics` 或 `chats`。 |
| `date_from` | 是 | 开始日期，`YYYY-MM-DD`，包含当天。 |
| `date_to` | 是 | 结束日期，`YYYY-MM-DD`，包含当天。范围最长 **31 天**。 |
| `tz` | 否 | 用于解释日期并生成按天、按小时序列的 IANA 时区。默认 `Europe/Madrid`。示例：`UTC`、`America/Bogota`。 |
| `channels` | 否 | 以逗号分隔的渠道：`voice`、`whatsapp`、`web`、`instagram`、`facebook`… |
| `agents` | 否 | 以逗号分隔的智能体 ID（UUID）。 |
| `languages` | 否 | 以逗号分隔的用户语言代码，例如 `es,pt`。 |
| `limit` | 否 | 仅 `chats`。每页会话数，1–100。默认 100。 |
| `cursor` | 否 | 仅 `chats`。上一页返回的 `next_cursor`。 |

日期按 `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`）

按智能体和渠道每组返回一条记录，按会话数排序。

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=metrics&date_from=2026-10-01&date_to=2026-10-31&channels=voice"
```

```json theme={null}
{
  "tz": "Europe/Madrid",
  "from": "2026-09-30T22:00:00.000Z",
  "to": "2026-10-31T23:00:00.000Z",
  "data": [
    {
      "agent": { "id": "2fef9696-0662-4e49-bb83-7564ff25c7ef", "name": "Voice assistant" },
      "channel": "voice",
      "conversations": 12480,
      "escalated": 4120,
      "contained_pct": 67.0,
      "avg_duration_s": { "all": 109, "without_transfer": 120, "with_transfer": 86 },
      "whatsapp_notifications": 1210,
      "unique_users": 7950,
      "recontacts": 2480,
      "daily": [
        { "date": "2026-10-01", "conversations": 410, "escalated": 151 }
      ],
      "hourly": [
        { "hour": 9, "conversations": 1320 },
        { "hour": 10, "conversations": 1544 }
      ]
    }
  ]
}
```

| 字段 | 说明 |
| - | - |
| `agent` | 处理这些会话的 AI 智能体（`id`、`name`）。会话没有智能体时为 `null`。 |
| `channel` | 会话渠道。未记录时为 `n/a`。 |
| `conversations` | 范围内开始的会话数（语音渠道为通话数）。 |
| `escalated` | 转给人工的会话数（带有 `chat_escalated` 事件）。 |
| `contained_pct` | `(conversations − escalated) / conversations × 100`。AI 未转人工而处理的比例。**这不是解决率。** |
| `avg_duration_s` | 通话平均时长（秒）：总体、未转人工、已转人工。没有时长的渠道为 `null`（只有语音会记录时长）。 |
| `whatsapp_notifications` | 从这些会话发送的 WhatsApp 通知数（`notification_sent` 事件）。 |
| `unique_users` | 不同用户数（语音渠道为不同电话号码数）。 |
| `recontacts` | 在范围内有 2 个或以上会话的用户数。重复联系率 = `recontacts / unique_users`。 |
| `daily` | 按 `tz` 计算的每日会话数和转人工数。没有会话的日期不会出现。 |
| `hourly` | 按 `tz` 计算的每小时（0–23）会话数。没有会话的小时不会出现。 |

> [!TIP]
>
> **与上月对比**：每月各调用一次端点，共调用两次，然后计算差值。
> **仅统计有人工坐席当天的自主处理率**：使用 `daily`，只保留 `escalated > 0` 的日期。

## 会话（`type=chats`）

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

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://cloud.lovi.ai/functions/v1/analytics?type=chats&date_from=2026-10-01&date_to=2026-10-01&channels=voice&limit=100"
```

```json theme={null}
{
  "data": [
    {
      "id": "29d67962-119b-406c-b172-d66cf179975e",
      "created_at": "2026-10-01T05:58:40.4431Z",
      "ended_at": "2026-10-01T05:58:48Z",
      "last_message_at": null,
      "status": "aiagent",
      "channel": "voice",
      "phone": "34600000000",
      "language": "es",
      "agent": { "id": "2fef9696-0662-4e49-bb83-7564ff25c7ef", "name": "Voice assistant" },
      "escalated_to_human": true,
      "escalated_at": "2026-10-01T05:58:45.12Z",
      "attended_by_human": false,
      "human_agents": [],
      "whatsapp_notifications": 0,
      "inquiry_set": null,
      "parameters": {
        "channel": "voice",
        "call_length": 8,
        "phone_call": "+34600000000",
        "voice_inbound": true,
        "conversation_recording_url": "https://…"
      }
    }
  ],
  "next_cursor": "MjAyNi0xMC0wMVQwNjowMjoxMS4xMjM0NTZ8…"
}
```

| 字段 | 说明 |
| - | - |
| `id` | 会话 ID。 |
| `created_at`、`ended_at`、`last_message_at` | 开始、结束和最后一条消息的时间（UTC）。 |
| `status` | 会话当前由谁处理：`aiagent`、`human`、`queue`（等待人工）或 `push`（由通知发起）。 |
| `channel`、`language` | 为方便起见从 `parameters.channel` 和 `parameters.lang_user` 复制。如果通话没有保存 `channel`，则返回 `voice`。 |
| `phone` | 联系人电话号码，仅数字且不含 `+`（E.164 格式）；会话没有号码时为 `null`（例如网页小组件）。 |
| `agent` | 会话的 AI 智能体（`id`、`name`）。 |
| `escalated_to_human`、`escalated_at` | 是否转给了人工，以及转接时间（第一次转接）。 |
| `attended_by_human` | 人工坐席是否至少发送过一条消息。 |
| `human_agents` | 在会话中发过消息的人工坐席（`id`、`name`）。即使 `attended_by_human` 为 `true` 也可能为空：从外部 CRM 发送的消息不会归属到具体的人。 |
| `whatsapp_notifications` | 从该会话发送的 WhatsApp 通知数。 |
| `inquiry_set` | 会话来源的发送活动（inquiry set）：`id` 和 `name`（创建发送时设置的名称）。会话不是来自发送活动时为 `null`。如果该活动已不存在，`name` 可能为 `null`。 |
| `parameters` | 会话保存的**全部**参数，未经过滤。键取决于渠道和智能体配置（语音：`call_length`、`phone_call`、`voice_inbound`、`session_call_id`、`conversation_recording_url`…，以及智能体保存的任何自定义参数）。如果会话来自发送活动，`parameters.inquiry_set_id` 中是活动的**名称**；ID 在 `inquiry_set.id` 中。 |

### 分页

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

```python theme={null}
import requests

URL = "https://cloud.lovi.ai/functions/v1/analytics"
HEADERS = {"x-api-key": "YOUR_API_KEY"}
params = {"type": "chats", "date_from": "2026-10-01", "date_to": "2026-10-31", "channels": "voice"}

chats = []
while True:
    page = requests.get(URL, headers=HEADERS, params=params, timeout=60).json()
    chats.extend(page["data"])
    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

print(len(chats), "个会话")
```

## 错误

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

| 状态码 | 场景 |
| - | - |
| `400` | 缺少密钥（`Missing access_key parameter`）、`type` 无效、日期无效、范围超过 31 天，或 `tz`、`limit`、`agents`、`channels`、`cursor` 无效。 |
| `403` | 密钥存在，但没有 `analytics_api` 权限。 |
| `404` | 密钥无效或已撤销。 |
| `405` | 使用了 `GET` 以外的方法。 |
| `500` | 内部错误。请几秒后重试；如果问题持续，请联系支持并提供请求时间。 |

## 限制与最佳实践

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.