# Yhteenveto-API

API:n kautta on saatavilla kahdenlaisia tekoälyn kirjoittamia yhteenvetoja:

- **Chat-yhteenvedot** — lyhyt kertaus yhden yhteyshenkilön keskustelusta, joka luodaan pyynnöstä. Sama asia kuin chatin yhteenvetotoiminto (katso [Chat-yhteenveto](../chats/chat-interface.md#chat-summary)).
- **Päivittäiset yhteenvedot** — kerran päivässä tehtävä kooste kaikista keskusteluistasi, jonka [Päivittäiset yhteenvedot](../daily-summaries/daily-summaries.md) muodostaa joka aamu: tilastot, yksi markdown-lohko per osio ja kaikki tekoälyn niistä luomat tehtävät.

- **Perus-URL** — `https://api.dmchamp.com/v1`
- **Todennus** — API-avaimesi (katso [Todennus](authentication.md)). [Rajattu avain](api-keys.md#scoped-keys) tarvitsee `Summaries`-osion.
- **Virheet ja sivutus** — katso [Virheet ja sivutus](errors-and-pagination.md)

Kaikki alla olevat esimerkit näyttävät `?apiKey=`-kyselymuodon cURL-muodossa ja `X-API-Key`-otsikon JavaScriptissä ja Pythonissa – kumpi tahansa toimii jokaisessa päätepisteessä.

---

## Luo chat-yhteenveto

`POST /summaries` — lähetä yhteyshenkilön `phoneNumber` (maakoodilla) tai `email`; toinen näistä on pakollinen.

Tekoäly lukee yhteyshenkilön viimeisimmän **suljetun** keskustelun tai sen, joka on vielä auki, jos yhtään ei ole vielä suljettu, ja kirjoittaa siitä kertauksen. Kertaus tallennetaan yhteyshenkilölle (se näkyy sovelluksen yhteyshenkilöpaneelissa kohdassa **Yhteenvedot**) ja palautetaan vastauksessa, joten voit välittää sen suoraan CRM-järjestelmään, Slack-kanavalle tai sähköpostiin.

**Kustannus:** sama kuin yksi tekoälyvastaus agentin tekoälyn laatutasolla — Pro 1 krediitti, Max 0,25, Mini 0,15; omalla Anthropic-avaimellasi Pro maksaa 0. Pyyntö hylätään ennen kuin mitään luodaan, jos saldo ei kata sitä.

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

**Vastaus**

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

| Tila | Merkitys |
|---|---|
| `400` | Kumpaakaan, `phoneNumber` tai `email`, ei lähetetty. |
| `404` | Yhteyshenkilöä ei löydy, yhteyshenkilöllä ei ole vielä keskustelua tai keskustelussa ei ole viestejä. Rungon `message` kertoo, kumpi on kyseessä. |
| `500` | Luominen epäonnistui (esimerkiksi riittämättömien krediittien vuoksi). |

> **Automaatioresepti: varausvahvistussähköposti yhteenvedolla.** Lisää [automaatioon](../automations/automations.md) **Tapaaminen varattu** -liipaisimella **HTTP-pyyntö**-vaihe, joka kutsuu tätä päätepistettä `${trigger.contact.phone_number}`:lla (tai yhteyshenkilön sähköpostilla), ja sen jälkeen **Sähköposti**-vaihe, joka lisää HTTP-vaiheen vastauksesta `summary`:n yhdessä linkin kanssa chattiin (sovelluksesi osoite, jota seuraa `/chats/` ja liipaisimesta saatu yhteyshenkilön ID). Tiimisi saa varauksen kontekstin samassa sähköpostissa ilman, että heidän tarvitsee avata postilaatikkoa.

> **Yhteenvetojen lukeminen takaisin.** Ei ole olemassa päätepistettä, joka listaisi tallennetut chat-yhteenvedot. Säilytä vastauksen teksti, jos tarvitset sitä myöhemmin, tai luo se uudelleen (jokainen kutsu laskutetaan).

### Vaihtoehto: yhteyshenkilön ID:n mukaan

`POST /summaries/chat-summary` `{"contactId": "..."}`:llä tekee saman luomisen yhteyshenkilölle, jonka ID on jo hallussasi. Se vahvistaa vain onnistumisen (`{"success": true, "data": "Chat summary generated successfully"}`) eikä **palauta** tekstiä, joten käytä `POST /summaries`:a, kun haluat itse kertauksen. Tiimin jäsen, jonka avain on rajoitettu vain hänen omiin yhteyshenkilöihinsä, saa `404`:n yhteyshenkilölle, joka on kyseisen laajuuden ulkopuolella.

---

## Hae päivittäinen yhteenveto

`GET /summaries/daily/{date}` — `date` on `YYYY-MM-DD`. Palauttaa kyseisen päivän yhteenvedon tai `null` kohdassa `summary`, kun mitään ei ole vielä luotu, sekä osiokonfiguraatiosi.

**cURL**

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

**Vastaus**

```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` tai `failed` (kun `error` on asetettu). Kysy tätä päätepistettä uudelleenluonnin jälkeen, kunnes se lukee `completed`.
- **`sections`** — yksi markdown-merkkijono per osio, avaimena osion tunniste. Viisi vakio-osiota ovat `wins_losses_improvements`, `tasks_action_items`, `human_alerts_reviews`, `sentiment_analysis` ja `booked_meetings_sales`; osiot, jotka lisäät **Määritä**-kohdassa Päivittäiset yhteenvedot -sivulla, saavat `custom_…`-tunnisteen. Nimet ja järjestys toistetaan kohdassa `section_configs`.
- **`contact_map`** — näyttönimi yhteystiedon tunnisteeksi, jotta voit muuttaa tekstissä olevat nimet linkeiksi.
- **`auto_tasks`** / **`created_task_ids`** — tekoälyn poimimat toimintokohteet ja niistä luodut tehtävät (kun **Luo tehtäväkortteja toimintokohteista** on päällä).

| Tila | Merkitys |
|---|---|
| `400` | `date` ei ole `YYYY-MM-DD` tai se on tulevaisuudessa. |
| `403` | Päivittäiset yhteenvedot on kytketty pois päältä tililtä. |

> Haluatko mieluummin push-ilmoituksen kuin kyselyn? **Päivittäinen yhteenveto luotu** [webhook-tapahtuma](../integrations/webhooks.md) toimittaa saman hyötykuorman heti, kun aamuyhteenveto valmistuu.

---

## Päivittäisen yhteenvedon uudelleenluonti

`POST /summaries/daily/{date}/regenerate` — aloittaa uuden luonnin kyseiselle päivälle taustalla ja palauttaa välittömästi `status: "generating"` ja tyhjän `sections`. Kysy `GET /summaries/daily/{date}`, kunnes se valmistuu. Samat säännöt pätevät kuin sovelluksen **Yritä uudelleen** -linkissä.

Valinnainen runko `{"deleteTasks": false}` säilyttää edellisen suorituksen luomat tehtävät; oletusarvoisesti ne poistetaan ja luodaan uudelleen uuden yhteenvedon perusteella. Lähetä oikea totuusarvo (boolean) — merkkijono `"false"` jätetään huomiotta ja käsitellään oletusarvona.

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

---

## Pikaopas

| Tehtävä | Päätepiste |
|---|---|
| Luo chat-yhteenveto ja hae teksti | `POST /summaries` |
| Luo chat-yhteenveto yhteystiedon tunnisteen perusteella (ei palauta tekstiä) | `POST /summaries/chat-summary` |
| Lue päivän yhteenveto | `GET /summaries/daily/{date}` |
| Luo päivän yhteenveto uudelleen | `POST /summaries/daily/{date}/regenerate` |