# 摘要 API

API 提供两种 AI 生成的摘要：

- **聊天摘要** — 对单个联系人对话的简短回顾，按需生成。与聊天中的摘要控件功能相同（请参阅 [聊天摘要](../chats/chat-interface.md#chat-summary)）。
- **每日摘要** — [每日摘要](../daily-summaries/daily-summaries.md) 每天早上生成的跨所有对话的汇总：包含统计数据、每个部分的 Markdown 块以及 AI 从中创建的任何任务。

- **基础 URL** — `https://api.dmchamp.com/v1`
- **身份验证** — 您的 API 密钥（请参阅 [身份验证](authentication.md)）。[作用域密钥](api-keys.md#scoped-keys) 需要 `Summaries` 部分。
- **错误与分页** — 请参阅 [错误与分页](errors-and-pagination.md)

以下所有示例均展示了 cURL 中的 `?apiKey=` 查询形式，以及 JavaScript 和 Python 中的 `X-API-Key` 标头——两者均适用于所有端点。

---

## 生成聊天摘要

`POST /summaries` — 发送联系人的 `phoneNumber`（带国家代码）或 `email`；两者必填其一。

AI 会读取该联系人最近一次**已关闭**的对话，如果尚未关闭，则读取当前打开的对话，并对其进行回顾总结。该回顾会存储在联系人信息中（在应用内的联系人面板中显示在 **摘要** 下方），并会在响应中返回，以便您可以直接将其转发到 CRM、Slack 频道或电子邮件中。

**费用：** 与代理 AI 质量等级下的一次 AI 回复费用相同 — Pro 为 1 个积分，Max 为 0.25，Mini 为 0.15；如果您连接了自己的 Anthropic 密钥，Pro 的费用为 0。如果余额不足以支付，请求将在生成任何内容之前被拒绝。

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+31612345678"}'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/summaries", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ email: "jane@example.com" }),
});
const { summary } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://api.dmchamp.com/v1/summaries",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phoneNumber": "+31612345678"},
)
print(r.json()["summary"])
```

**响应**

```json
{
  "success": true,
  "message": "Chat summary generated successfully",
  "summary": "Jane asked about the 10-session package for her two children (ages 6 and 9) and preferred Saturday mornings. She booked a trial lesson for Saturday at 10:00 and wants to know whether siblings get a discount."
}
```

| 状态 | 含义 |
|---|---|
| `400` | 未发送 `phoneNumber` 或 `email`。 |
| `404` | 没有匹配的联系人，联系人尚无对话，或对话中没有消息。响应正文的 `message` 会说明具体原因。 |
| `500` | 生成失败（例如，积分不足）。 |

> **自动化方案：带回顾的预约邮件。** 在 **预约已预订** 触发器的 [自动化](../automations/automations.md) 中，添加一个调用此端点的 **HTTP 请求** 步骤（使用 `${trigger.contact.phone_number}` 或联系人的电子邮件），然后添加一个 **电子邮件** 步骤，插入来自 HTTP 步骤响应的 `summary`，并附上聊天链接（您的应用地址后跟 `/chats/` 和触发器中的联系人 ID）。您的团队无需打开收件箱，即可在同一封邮件中获取预约背景信息。

> **读取已存储的摘要。** 目前没有列出已存储聊天摘要的端点。如果您以后需要，请保留响应中的文本，或者再次生成（每次调用都会计费）。

### 替代方案：按联系人 ID

使用 `{"contactId": "..."}` 的 `POST /summaries/chat-summary` 可为您已拥有 ID 的联系人执行相同的生成操作。它仅确认成功（`{"success": true, "data": "Chat summary generated successfully"}`），**不**返回文本，因此当您需要回顾内容本身时，请使用 `POST /summaries`。如果团队成员的密钥仅限于其分配的联系人，则对于该范围之外的联系人，将收到 `404`。

---

## 获取每日摘要

`GET /summaries/daily/{date}` — `date` 为 `YYYY-MM-DD`。返回当天的摘要，如果尚未生成，则在 `summary` 下返回 `null`，以及您的部分配置。

**cURL**

```bash
curl "https://api.dmchamp.com/v1/summaries/daily/2026-09-08?apiKey=YOUR_API_KEY"
```

**响应**

```json
{
  "success": true,
  "data": {
    "summary": {
      "date": "2026-09-08",
      "status": "completed",
      "generated_at": "2026-09-09T05:02:11.000Z",
      "stats": {
        "total_conversations": 42,
        "total_messages_sent": 310,
        "total_messages_received": 268,
        "human_alerts": 3,
        "bookings": 5,
        "new_contacts": 11,
        "sales": 2
      },
      "sections": {
        "wins_losses_improvements": "## Wins\n- ...",
        "tasks_action_items": "- Call Jane back about the sibling discount",
        "human_alerts_reviews": "...",
        "sentiment_analysis": "...",
        "booked_meetings_sales": "..."
      },
      "contact_map": { "Jane Doe": "uid_whatsapp_31612345678" },
      "auto_tasks": [],
      "created_task_ids": []
    },
    "section_configs": [
      { "id": "wins_losses_improvements", "name": "Wins, Losses & Improvements", "enabled": true, "position": 0 }
    ]
  }
}
```

- **`status`** — `pending`、`generating`、`completed` 或 `failed`（需设置 `error`）。在重新生成后轮询此端点，直到其状态显示为 `completed`。
- **`sections`** — 每个部分一个 Markdown 字符串，以部分 ID 为键。五个标准部分为 `wins_losses_improvements`、`tasks_action_items`、`human_alerts_reviews`、`sentiment_analysis` 和 `booked_meetings_sales`；您在“每日摘要”页面的**配置**下添加的部分将获得一个 `custom_…` ID。名称和顺序在 `section_configs` 中回显。
- **`contact_map`** — 显示名称到联系人 ID 的映射，以便您可以将文本中的名称转换为链接。
- **`auto_tasks`** / **`created_task_ids`** — AI 提取的行动项以及由此创建的任务（当**从行动项创建任务卡片**开启时）。

| 状态 | 含义 |
|---|---|
| `400` | `date` 未 `YYYY-MM-DD`，或日期在未来。 |
| `403` | 账户已关闭“每日摘要”功能。 |

> 想要推送而非轮询？**每日摘要已创建** [webhook 事件](../integrations/webhooks.md) 会在早间摘要完成时立即发送相同的负载。

---

## 重新生成每日摘要

`POST /summaries/daily/{date}/regenerate` — 在后台为当天开始新的生成，并立即返回 `status: "generating"` 和空的 `sections`。轮询 `GET /summaries/daily/{date}` 直到完成。适用规则与应用中的**重试**链接相同。

可选的正文 `{"deleteTasks": false}` 可保留上次运行创建的任务；默认情况下，这些任务会被删除并根据新摘要重新创建。请发送真实的布尔值 — 字符串 `"false"` 会被忽略并视为默认值。

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries/daily/2026-09-08/regenerate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deleteTasks": false}'
```

---

## 快速参考

| 任务 | 端点 |
|---|---|
| 生成聊天摘要并获取文本 | `POST /summaries` |
| 按联系人 ID 生成聊天摘要（不返回文本） | `POST /summaries/chat-summary` |
| 读取当天的摘要 | `GET /summaries/daily/{date}` |
| 重新生成当天的摘要 | `POST /summaries/daily/{date}/regenerate` |