# API Tóm tắt

Có hai loại tóm tắt do AI viết khả dụng thông qua API:

- **Tóm tắt trò chuyện** — bản tóm tắt ngắn gọn về cuộc hội thoại của một liên hệ, được tạo theo yêu cầu. Tương tự như tính năng điều khiển tóm tắt trong trò chuyện (xem [Tóm tắt Trò chuyện](../chats/chat-interface.md#chat-summary)).
- **Tóm tắt hàng ngày** — bản tổng hợp một lần mỗi ngày trên tất cả các cuộc hội thoại của bạn mà [Tóm tắt Hàng ngày](../daily-summaries/daily-summaries.md) tạo ra vào mỗi buổi sáng: số liệu thống kê, một khối markdown cho mỗi phần và bất kỳ tác vụ nào mà AI đã tạo từ đó.

- **URL cơ sở** — `https://api.dmchamp.com/v1`
- **Xác thực** — khóa API của bạn (xem [Xác thực](authentication.md)). Một [khóa có phạm vi](api-keys.md#scoped-keys) cần phần `Summaries`.
- **Lỗi & phân trang** — xem [Lỗi & Phân trang](errors-and-pagination.md)

Tất cả các ví dụ dưới đây đều hiển thị dạng truy vấn `?apiKey=` trong cURL và tiêu đề `X-API-Key` trong JavaScript và Python — cả hai đều hoạt động trên mọi endpoint.

---

## Tạo tóm tắt trò chuyện

`POST /summaries` — gửi `phoneNumber` của liên hệ (kèm mã quốc gia) hoặc `email`; bắt buộc phải có một trong hai.

AI đọc cuộc hội thoại **đã đóng** gần đây nhất của liên hệ, hoặc cuộc hội thoại vẫn đang mở nếu chưa có cuộc hội thoại nào đóng, và viết bản tóm tắt về cuộc hội thoại đó. Bản tóm tắt được lưu trữ trên liên hệ (nó xuất hiện trong phần **Tóm tắt** trong bảng liên hệ trong ứng dụng) và được trả về trong phản hồi, vì vậy bạn có thể chuyển tiếp trực tiếp đến CRM, kênh Slack hoặc email.

**Chi phí:** tương đương với một phản hồi AI ở cấp độ Chất lượng AI của Đại lý — Pro 1 tín dụng, Max 0.25, Mini 0.15; với khóa Anthropic của riêng bạn được kết nối, Pro tốn 0. Yêu cầu sẽ bị từ chối trước khi bất kỳ nội dung nào được tạo nếu số dư không đủ chi trả.

**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"])
```

**Phản hồi**

```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."
}
```

| Trạng thái | Ý nghĩa |
|---|---|
| `400` | Không gửi `phoneNumber` cũng không gửi `email`. |
| `404` | Không có liên hệ nào khớp, liên hệ chưa có cuộc hội thoại nào hoặc cuộc hội thoại không có tin nhắn. `message` của phần thân sẽ cho biết lý do. |
| `500` | Tạo không thành công (ví dụ: không đủ tín dụng). |

> **Công thức tự động hóa: email đặt lịch kèm bản tóm tắt.** Trong một [tự động hóa](../automations/automations.md) trên trình kích hoạt **Đã đặt lịch hẹn**, hãy thêm bước **Yêu cầu HTTP** gọi điểm cuối này với `${trigger.contact.phone_number}` (hoặc email của liên hệ), sau đó là bước **Email** chèn `summary` từ phản hồi của bước HTTP cùng với liên kết đến cuộc trò chuyện (địa chỉ ứng dụng của bạn theo sau là `/chats/` và ID liên hệ từ trình kích hoạt). Nhóm của bạn sẽ nhận được ngữ cảnh của việc đặt lịch trong cùng một email mà không cần mở hộp thư đến.

> **Đọc lại các bản tóm tắt.** Không có điểm cuối nào liệt kê các bản tóm tắt trò chuyện đã lưu. Hãy giữ lại văn bản từ phản hồi nếu bạn cần sau này, hoặc tạo lại (mỗi lần gọi đều bị tính phí).

### Thay thế: theo ID liên hệ

`POST /summaries/chat-summary` với `{"contactId": "..."}` thực hiện tạo tương tự cho một liên hệ mà bạn đã có ID. Nó chỉ xác nhận thành công (`{"success": true, "data": "Chat summary generated successfully"}`) và **không** trả về văn bản, vì vậy hãy sử dụng `POST /summaries` khi bạn muốn chính bản tóm tắt đó. Một thành viên trong nhóm có khóa bị giới hạn trong các liên hệ được chỉ định của họ sẽ nhận được `404` cho một liên hệ nằm ngoài phạm vi đó.

---

## Nhận tóm tắt hàng ngày

`GET /summaries/daily/{date}` — `date` là `YYYY-MM-DD`. Trả về bản tóm tắt cho ngày đó, hoặc `null` dưới `summary` khi chưa có bản tóm tắt nào được tạo, cộng với cấu hình phần của bạn.

**cURL**

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

**Phản hồi**

```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` hoặc `failed` (với `error` được thiết lập). Hãy thăm dò điểm cuối này sau khi tạo lại cho đến khi nó đọc là `completed`.
- **`sections`** — một chuỗi markdown cho mỗi phần, được khóa theo id phần. Năm phần tiêu chuẩn là `wins_losses_improvements`, `tasks_action_items`, `human_alerts_reviews`, `sentiment_analysis` và `booked_meetings_sales`; các phần bạn thêm trong **Cấu hình** trên trang Tóm tắt hàng ngày sẽ có id `custom_…`. Tên và thứ tự được phản hồi trong `section_configs`.
- **`contact_map`** — tên hiển thị đến ID liên hệ, để bạn có thể chuyển đổi tên trong văn bản thành liên kết.
- **`auto_tasks`** / **`created_task_ids`** — các mục hành động mà AI đã trích xuất và các tác vụ mà nó tạo ra từ đó (khi **Tạo thẻ tác vụ từ các mục hành động** được bật).

| Trạng thái | Ý nghĩa |
|---|---|
| `400` | `date` không phải là `YYYY-MM-DD`, hoặc là trong tương lai. |
| `403` | Tóm tắt hàng ngày đã bị tắt cho tài khoản này. |

> Bạn thích đẩy dữ liệu hơn là thăm dò? [Sự kiện webhook](../integrations/webhooks.md) **Daily Summary Created** (Tóm tắt hàng ngày đã được tạo) sẽ gửi cùng một payload ngay khi bản tóm tắt buổi sáng hoàn tất.

---

## Tạo lại bản tóm tắt hàng ngày

`POST /summaries/daily/{date}/regenerate` — bắt đầu một quá trình tạo mới cho ngày đó trong nền và trả về ngay lập tức với `status: "generating"` và `sections` trống. Hãy thăm dò `GET /summaries/daily/{date}` cho đến khi nó hoàn tất. Các quy tắc tương tự áp dụng như đối với liên kết **Thử lại** trong ứng dụng.

Phần thân tùy chọn `{"deleteTasks": false}` giữ lại các tác vụ mà lần chạy trước đã tạo; theo mặc định, chúng sẽ bị xóa và tạo lại từ bản tóm tắt mới. Hãy gửi một giá trị boolean thực — chuỗi `"false"` sẽ bị bỏ qua và được coi là mặc định.

```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}'
```

---

## Tham khảo nhanh

| Tác vụ | Điểm cuối |
|---|---|
| Tạo bản tóm tắt trò chuyện và lấy văn bản | `POST /summaries` |
| Tạo bản tóm tắt trò chuyện theo ID liên hệ (không trả về văn bản) | `POST /summaries/chat-summary` |
| Đọc bản tóm tắt trong ngày | `GET /summaries/daily/{date}` |
| Tạo lại bản tóm tắt trong ngày | `POST /summaries/daily/{date}/regenerate` |