# Zusammenfassungs-API

Über die API sind zwei Arten von KI-generierten Zusammenfassungen verfügbar:

- **Chat-Zusammenfassungen** — eine kurze Zusammenfassung der Konversation eines Kontakts, die bei Bedarf erstellt wird. Dies entspricht dem Zusammenfassungs-Steuerelement in einem Chat (siehe [Chat-Zusammenfassung](../chats/chat-interface.md#chat-summary)).
- **Tägliche Zusammenfassungen** — der tägliche Überblick über alle Ihre Konversationen, den [Tägliche Zusammenfassungen](../daily-summaries/daily-summaries.md) jeden Morgen erstellt: Statistiken, ein Markdown-Block pro Abschnitt und alle Aufgaben, die die KI daraus erstellt hat.

- **Basis-URL** — `https://api.dmchamp.com/v1`
- **Authentifizierung** — Ihr API-Schlüssel (siehe [Authentifizierung](authentication.md)). Ein [bereichsbeschränkter Schlüssel](api-keys.md#scoped-keys) benötigt den Abschnitt `Summaries`.
- **Fehler & Paging** — siehe [Fehler & Paginierung](errors-and-pagination.md)

Alle nachstehenden Beispiele zeigen die `?apiKey=`-Abfrageform in cURL und den `X-API-Key`-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

---

## Chat-Zusammenfassung generieren

`POST /summaries` — senden Sie die `phoneNumber` des Kontakts (mit Ländervorwahl) oder die `email`; einer der beiden Werte ist erforderlich.

Die KI liest die zuletzt **geschlossene** Konversation des Kontakts oder diejenige, die noch offen ist, falls noch keine geschlossen wurde, und schreibt eine Zusammenfassung. Die Zusammenfassung wird beim Kontakt gespeichert (sie erscheint unter **Zusammenfassungen** im Kontaktbereich der App) und in der Antwort zurückgegeben, sodass Sie sie direkt an ein CRM, einen Slack-Kanal oder eine E-Mail weiterleiten können.

**Kosten:** dieselben wie für eine KI-Antwort auf der KI-Qualitätsstufe des Agenten — Pro 1 Credit, Max 0,25, Mini 0,15; bei Verwendung Ihres eigenen Anthropic-Schlüssels kostet Pro 0. Die Anfrage wird abgelehnt, bevor etwas generiert wird, wenn das Guthaben nicht ausreicht.

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

**Antwort**

```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 | Bedeutung |
|---|---|
| `400` | Weder `phoneNumber` noch `email` wurde gesendet. |
| `404` | Es wurde kein Kontakt gefunden, der Kontakt hat noch keine Konversation oder die Konversation enthält keine Nachrichten. Der `message` im Body gibt an, welcher Fall vorliegt. |
| `500` | Generierung fehlgeschlagen (z. B. nicht genügend Credits). |

> **Automatisierungsrezept: Buchungs-E-Mail mit Zusammenfassung.** Fügen Sie in einer [Automatisierung](../automations/automations.md) beim Auslöser **Termin gebucht** einen **HTTP-Anfrage**-Schritt hinzu, der diesen Endpunkt mit `${trigger.contact.phone_number}` (oder der E-Mail-Adresse des Kontakts) aufruft, gefolgt von einem **E-Mail**-Schritt, der die `summary` aus der Antwort des HTTP-Schritts zusammen mit einem Link zum Chat einfügt (die Adresse Ihrer App gefolgt von `/chats/` und der Kontakt-ID aus dem Auslöser). Ihr Team erhält den Kontext der Buchung in derselben E-Mail, ohne den Posteingang öffnen zu müssen.

> **Zusammenfassungen erneut lesen.** Es gibt keinen Endpunkt, der gespeicherte Chat-Zusammenfassungen auflistet. Bewahren Sie den Text aus der Antwort auf, wenn Sie ihn später benötigen, oder generieren Sie ihn erneut (jeder Aufruf wird berechnet).

### Alternative: nach Kontakt-ID

`POST /summaries/chat-summary` mit `{"contactId": "..."}` führt dieselbe Generierung für einen Kontakt durch, dessen ID Sie bereits besitzen. Es bestätigt nur den Erfolg (`{"success": true, "data": "Chat summary generated successfully"}`) und gibt den Text **nicht** zurück. Verwenden Sie daher `POST /summaries`, wenn Sie die Zusammenfassung selbst benötigen. Ein Teammitglied, dessen Schlüssel auf zugewiesene Kontakte beschränkt ist, erhält `404` für einen Kontakt außerhalb dieses Bereichs.

---

## Tägliche Zusammenfassung abrufen

`GET /summaries/daily/{date}` — `date` ist `YYYY-MM-DD`. Gibt die Zusammenfassung für diesen Tag zurück oder `null` unter `summary`, wenn noch keine generiert wurde, zuzüglich Ihrer Abschnittskonfiguration.

**cURL**

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

**Antwort**

```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` oder `failed` (mit gesetztem `error`). Fragen Sie diesen Endpunkt nach einer Neugenerierung ab, bis er `completed` anzeigt.
- **`sections`** — ein Markdown-String pro Abschnitt, identifiziert durch die Abschnitts-ID. Die fünf Standardabschnitte sind `wins_losses_improvements`, `tasks_action_items`, `human_alerts_reviews`, `sentiment_analysis` und `booked_meetings_sales`; Abschnitte, die Sie unter **Konfigurieren** auf der Seite „Tägliche Zusammenfassungen“ hinzufügen, erhalten eine `custom_…`-ID. Namen und Reihenfolge werden in `section_configs` wiedergegeben.
- **`contact_map`** — Anzeigename zu Kontakt-ID, damit Sie die Namen im Text in Links umwandeln können.
- **`auto_tasks`** / **`created_task_ids`** — die von der KI extrahierten Aktionspunkte und die daraus erstellten Aufgaben (wenn **Aufgabenkarten aus Aktionspunkten erstellen** aktiviert ist).

| Status | Bedeutung |
|---|---|
| `400` | `date` ist nicht `YYYY-MM-DD` oder liegt in der Zukunft. |
| `403` | Tägliche Zusammenfassungen sind für das Konto deaktiviert. |

> Bevorzugen Sie Push statt Polling? Das **Daily Summary Created** [Webhook-Ereignis](../integrations/webhooks.md) liefert denselben Payload in dem Moment, in dem eine morgendliche Zusammenfassung fertiggestellt wird.

---

## Tägliche Zusammenfassung neu generieren

`POST /summaries/daily/{date}/regenerate` — startet eine neue Generierung für diesen Tag im Hintergrund und kehrt sofort mit `status: "generating"` und leerem `sections` zurück. Fragen Sie `GET /summaries/daily/{date}` ab, bis der Vorgang abgeschlossen ist. Es gelten dieselben Regeln wie für den Link **Erneut versuchen** in der App.

Der optionale Body `{"deleteTasks": false}` behält die Aufgaben bei, die beim vorherigen Durchlauf erstellt wurden; standardmäßig werden diese gelöscht und aus der neuen Zusammenfassung neu erstellt. Senden Sie einen echten Boolean — der String `"false"` wird ignoriert und als Standard behandelt.

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

---

## Kurzübersicht

| Aufgabe | Endpunkt |
|---|---|
| Chat-Zusammenfassung generieren und Text abrufen | `POST /summaries` |
| Chat-Zusammenfassung nach Kontakt-ID generieren (kein Text zurückgegeben) | `POST /summaries/chat-summary` |
| Zusammenfassung eines Tages lesen | `GET /summaries/daily/{date}` |
| Zusammenfassung eines Tages neu generieren | `POST /summaries/daily/{date}/regenerate` |