# API Ringkasan

Dua jenis ringkasan yang ditulis oleh AI tersedia melalui API:

- **Ringkasan obrolan** — rekap singkat percakapan satu kontak, yang dibuat sesuai permintaan. Sama dengan kontrol ringkasan dalam obrolan (lihat [Ringkasan Obrolan](../chats/chat-interface.md#chat-summary)).
- **Ringkasan harian** — rangkuman sekali sehari di seluruh percakapan Anda yang dibuat oleh [Ringkasan Harian](../daily-summaries/daily-summaries.md) setiap pagi: statistik, satu blok markdown per bagian, dan tugas apa pun yang dibuat AI darinya.

- **URL Dasar** — `https://api.dmchamp.com/v1`
- **Autentikasi** — kunci API Anda (lihat [Autentikasi](authentication.md)). [Kunci berlingkup](api-keys.md#scoped-keys) memerlukan bagian `Summaries`.
- **Error & penomoran halaman** — lihat [Error & Penomoran Halaman](errors-and-pagination.md)

Semua contoh di bawah ini menunjukkan formulir kueri `?apiKey=` dalam cURL dan header `X-API-Key` dalam JavaScript dan Python — keduanya berfungsi di setiap endpoint.

---

## Membuat ringkasan obrolan

`POST /summaries` — kirim `phoneNumber` kontak (dengan kode negara) atau `email`; salah satu dari keduanya wajib diisi.

AI membaca percakapan **tertutup** terbaru milik kontak, atau percakapan yang masih terbuka jika belum ada yang ditutup, lalu menulis rekapnya. Rekap tersebut disimpan pada kontak (muncul di bawah **Ringkasan** di panel kontak dalam aplikasi) dan dikembalikan dalam respons, sehingga Anda dapat meneruskannya langsung ke CRM, saluran Slack, atau email.

**Biaya:** sama dengan satu balasan AI pada tingkat Kualitas AI Agen — Pro 1 kredit, Max 0,25, Mini 0,15; dengan kunci Anthropic Anda sendiri yang terhubung, Pro berbiaya 0. Permintaan ditolak sebelum ada yang dibuat jika saldo tidak mencukupi.

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

**Respons**

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

| Status | Arti |
|---|---|
| `400` | Baik `phoneNumber` maupun `email` tidak dikirim. |
| `404` | Tidak ada kontak yang cocok, kontak belum memiliki percakapan, atau percakapan tidak memiliki pesan. `message` pada body menjelaskan alasannya. |
| `500` | Pembuatan gagal (misalnya, kredit tidak cukup). |

> **Resep otomatisasi: email pemesanan dengan rekap.** Dalam [otomatisasi](../automations/automations.md) pada pemicu **Janji temu dipesan**, tambahkan langkah **Permintaan HTTP** yang memanggil endpoint ini dengan `${trigger.contact.phone_number}` (atau email kontak), lalu langkah **Email** yang menyisipkan `summary` dari respons langkah HTTP beserta tautan ke obrolan (alamat aplikasi Anda diikuti `/chats/` dan ID kontak dari pemicu). Tim Anda mendapatkan konteks pemesanan dalam email yang sama, tanpa harus membuka kotak masuk.

> **Membaca kembali ringkasan.** Tidak ada endpoint yang mencantumkan ringkasan obrolan yang tersimpan. Simpan teks dari respons jika Anda membutuhkannya nanti, atau buat kembali (setiap panggilan akan dikenakan biaya).

### Alternatif: berdasarkan ID kontak

`POST /summaries/chat-summary` dengan `{"contactId": "..."}` melakukan pembuatan yang sama untuk kontak yang ID-nya sudah Anda miliki. Ini hanya mengonfirmasi keberhasilan (`{"success": true, "data": "Chat summary generated successfully"}`) dan **tidak** mengembalikan teksnya, jadi gunakan `POST /summaries` jika Anda menginginkan rekapnya itu sendiri. Anggota tim yang kuncinya dibatasi pada kontak yang ditugaskan kepada mereka akan mendapatkan `404` untuk kontak di luar cakupan tersebut.

---

## Mendapatkan ringkasan harian

`GET /summaries/daily/{date}` — `date` adalah `YYYY-MM-DD`. Mengembalikan ringkasan untuk hari tersebut, atau `null` di bawah `summary` jika belum ada yang dibuat, ditambah konfigurasi bagian Anda.

**cURL**

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

**Respons**

```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` atau `failed` (dengan `error` diatur). Lakukan polling pada endpoint ini setelah regenerasi hingga terbaca `completed`.
- **`sections`** — satu string markdown per bagian, dikunci berdasarkan id bagian. Lima bagian standar adalah `wins_losses_improvements`, `tasks_action_items`, `human_alerts_reviews`, `sentiment_analysis` dan `booked_meetings_sales`; bagian yang Anda tambahkan di bawah **Konfigurasi** pada halaman Ringkasan Harian mendapatkan id `custom_…`. Nama dan urutan digemakan di `section_configs`.
- **`contact_map`** — nama tampilan ke ID kontak, sehingga Anda dapat mengubah nama dalam teks menjadi tautan.
- **`auto_tasks`** / **`created_task_ids`** — item tindakan yang diekstraksi oleh AI dan tugas yang dibuatnya dari item tersebut (saat **Buat kartu tugas dari item tindakan** aktif).

| Status | Arti |
|---|---|
| `400` | `date` tidak `YYYY-MM-DD`, atau terjadi di masa mendatang. |
| `403` | Ringkasan Harian dimatikan untuk akun tersebut. |

> Lebih suka push daripada polling? [Peristiwa webhook](../integrations/webhooks.md) **Ringkasan Harian Dibuat** mengirimkan payload yang sama saat ringkasan pagi selesai.

---

## Regenerasi ringkasan harian

`POST /summaries/daily/{date}/regenerate` — memulai pembuatan baru untuk hari itu di latar belakang dan segera kembali dengan `status: "generating"` dan `sections` kosong. Lakukan polling pada `GET /summaries/daily/{date}` hingga selesai. Aturan yang sama berlaku seperti untuk tautan **Coba lagi** di aplikasi.

Body opsional `{"deleteTasks": false}` menyimpan tugas yang dibuat oleh proses sebelumnya; secara default, tugas tersebut dihapus dan dibuat ulang dari ringkasan baru. Kirim boolean yang sebenarnya — string `"false"` diabaikan dan diperlakukan sebagai default.

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

---

## Referensi cepat

| Tugas | Endpoint |
|---|---|
| Menghasilkan ringkasan obrolan dan mendapatkan teksnya | `POST /summaries` |
| Menghasilkan ringkasan obrolan berdasarkan ID kontak (tidak ada teks yang dikembalikan) | `POST /summaries/chat-summary` |
| Membaca ringkasan hari ini | `GET /summaries/daily/{date}` |
| Meregenerasi ringkasan hari ini | `POST /summaries/daily/{date}/regenerate` |