# AI-agentien API

**AI-agentti** on bottisi aivot: sen ohjeet, persoonallisuus, kieli, tietämys ja työkalut. Luot agentin kerran ja ohjaat sitten liikenteen sille. Tämä opas kattaa kaiken, mitä voit tehdä agentilla API:n kautta — luoda sen, määrittää sen asetukset, antaa sille tietämystä ja työkaluja, tarkistaa sen luonnokset ja reitittää keskusteluja sille.

- **Perus-URL** — `https://api.dmchamp.com/v1`
- **Todennus** — API-avaimesi (katso [Todennus](authentication.md))
- **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ä.

Jos agentit käsitteenä ovat sinulle uusia, lue ensin [AI-agentit](../ai-agents/ai-agents.md).

::: master-only
> **Toimistot:** jokainen tämän sivun päätepiste hyväksyy `sub_account_id`-parametrin, joten voit rakentaa ja määrittää asiakkaan agentin toimistoavaimellasi. Lähetä se kyselyparametrina. Katso [API toimistoille](../agency/api-for-agencies.md).
:::

---

## Miten agentti muodostuu

Neljä asiaa hallitaan erikseen, ja on hyödyllistä tietää, mikä on mikä ennen kuin aloitat:

| Osa | Mikä se on | Missä se määritetään |
|---|---|---|
| **Asetukset** | Ohjeet, säännöt, tavoite, persoonallisuus, kieli, AI-taso, ajanvaraus ja jatkotoimenpiteiden käyttäytyminen | `PUT /agents/{agentId}` tai tarkempi `PUT /agents/{agentId}/bot-config` |
| **Tietämys** | UKK:t ja tietolähteet (sivut ja asiakirjat, jotka alusta on lukenut puolestasi) | [UKK-API](faqs.md) ja `POST /agents/{agentId}/kb-sources` |
| **Työkalut** | Mukautetut funktiot ja MCP-palvelimet, joita agentti voi kutsua kesken keskustelun | `POST /agents/{agentId}/custom-functions` ja `POST /agents/{agentId}/mcp-servers` |
| **Reititys** | Mitkä kanavat ja keskustelut todella tavoittavat tämän agentin | Aloituspisteet — `PUT /entry-points/channel-defaults` ja `POST /agents/{agentId}/entry-points` |

> **Uusi agentti ei vastaa kenellekään, ennen kuin reitität liikennettä sille.** Agentin luominen ei aseta sitä kanavalle. Tämä on vaihe, jonka useimmat integraatiot unohtavat — katso [Keskustelujen reitittäminen agentille](#routing-conversations-to-an-agent) tämän sivun lopusta.

---

## Agentti-objekti

Täysi agenttiasiakirja on suuri — useita satoja kilotavuja, pääasiassa sen UKK-luettelo, tietolähteet ja kaikki verkkosivustoltasi luettu sivusisältö. Tämän vuoksi listaus palauttaa lyhyen **yhteenvetorivin** per agentti, kun pyydät sitä:

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| `id` | string | Agentin yksilöllinen tunniste. |
| `name` | string \| null | Agentin nimi, kuten se näkyy hallintapaneelissa. |
| `active` | boolean \| null | Saako agentti tällä hetkellä vastata. |
| `language` | string \| null | Kieli, jolla agentti vastaa. |
| `goal` | string \| null | Mitä agentti tavoittelee, lyhennettynä ensimmäiseen 200 merkkiin (perässä oleva ellipsi tarkoittaa, että tekstiä on lyhennetty). |
| `tags` | array \| null | Agentin tägityssäännöt. |
| `anthropic_model` | string \| null | AI-laatutaso: `standard`, `economy`, `max` tai `mini`. |
| `ai_speed` | string \| null | Kuinka paljon päättelyä agentti soveltaa ennen vastaamista: `fast`, `fast_thinker`, `balanced` tai `thorough`. |
| `enable_bookings` | boolean \| null | Voiko agentti varata aikoja. |
| `enable_follow_ups` | boolean \| null | Lähettääkö agentti jatkoviestiä. |
| `faq_refs_count` | integer | Kuinka monta UKK-kysymystä on tämän agentin tietokannassa. |
| `kb_source_refs_count` | integer | Kuinka monta tietolähdettä siihen on linkitetty. |
| `created_at` | integer \| null | Luomisaika, epoch-millisekunteina. |
| `last_modified_at` | integer \| null | Viimeisin muutos, epoch-millisekunteina. |

Täysi asiakirja lisää kaiken muun: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, linkitetyt UKK- ja tietolähdeluettelot, generoidut tekstilohkot ja mahdolliset suoritustilat (`tag_generation`, `optimize_run`).

> Jotkin vastaukset sisältävät myös `substrate_campaign_id`-kentän. Se on vanhemmilla tileillä säilytetty sisäinen tietue; sinun ei tarvitse koskaan tehdä sille mitään, ja uudemmilla tileillä se on `null` tai puuttuu kokonaan.

---

## Listaa agentit

`GET /agents` — jokainen tilin agentti, uusimmasta alkaen.

Tämä päätepiste **ei ole sivutettu**. Oletusarvoisesti jokainen agentti palautetaan täydellisellä konfiguraatiollaan, mikä on raskasta: yksi agentti voi olla kooltaan 580 kt ja 64 agentin tili yli 3 Mt. Välitä `view=summary`, jos haluat lyhyen rivin per agentti, ja lue sitten haluamasi agentti kohdasta [Hae agentti](#get-an-agent).

**Kyselyparametrit**

| Parametri | Kuvaus |
|---|---|
| `view` | Aseta arvoon `summary`, jos haluat lyhyet rivit. Mikä tahansa muu arvo palauttaa `400`. Jätä pois, jos haluat täydelliset dokumentit. |
| `fields` | Koskee vain yhdessä `view=summary`-parametrin kanssa. Pilkuilla eroteltu luettelo säilytettävistä yhteenvetoavaimista, esimerkiksi `id,name,active`. `id` sisällytetään aina; tuntemattomat nimet jätetään huomiotta. |

**cURL**

```bash
curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.dmchamp.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**Vastaus** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## Luo agentti

`POST /agents` — vain `name` on välttämätön; lähetä sen mukana kaikki konfiguraatiot, jotka jo tiedät. Uusi agentti on oletusarvoisesti aktiivinen.

**Pyynnön kentät** (kaikki valinnaisia, paitsi `name`)

| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| `name` | string | Agentin nimi. |
| `active` | boolean | Voiko se vastata heti. Oletusarvo on `true`. |
| `language` | string | Kieli, jolla agentti vastaa. |
| `instructions` | string | Ensisijaiset ohjeet, jotka ohjaavat sitä, miten se puhuu yhteyshenkilöille. |
| `rules` | string | Tiukat säännöt, joita sen on aina noudatettava. |
| `goal` | string | Lopputulos, jota kohti sen tulisi työskennellä. |
| `personality` | string | Äänensävy ja persoonallisuus. |
| `availability` | object | Aktiiviset tunnit arkipäivisin — katso [Aseta aktiiviset tunnit](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` tai `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` tai `mini`. |
| `scrape_urls` | string[] | Sivut, joita luetaan ja joista agentin ohjeet muodostetaan. |

**Agentin rakentaminen verkkosivustoltasi.** Sisällytä `scrape_urls`, niin alusta lukee kyseiset sivut ja kirjoittaa ohjeet puolestasi. Vastaus kertoo, onko kyseinen luonti alkanut, jotta tiedät, pitääkö agentin edistymistä kysellä. |

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.dmchamp.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**Vastaus** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

`agent_generation_queued` on `true`, kun alusta on aloittanut ohjeiden kirjoittamisen toimittamiltasi sivuilta.

`400` tarkoittaa, että runko ei ollut JSON-objekti, kenttä hylättiin tai agentti ylittää suunnitelmasi salliman konfiguraatiokoon. `403` tarkoittaa, että tilillä ei ole oikeutta käyttää jotakin lähettämistäsi asetuksista — esimerkiksi tekoälytasoa, jota tilin tarjoaja ei ole myöntänyt.

---

## Hae agentti

`GET /agents/{agentId}`

Välitä `fields` pilkuilla eroteltuna luettelona saadaksesi takaisin vain tarvitsemasi tiedot, esimerkiksi `fields=name,active,goal`. `id` sisällytetään aina, ja nimet, joita ei ole agentilla, jätetään huomiotta sen sijaan, että ne hylättäisiin. Jätä pois, jos haluat koko dokumentin.

**cURL**

```bash
curl "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

Agentti, jota ei ole tililläsi, palauttaa `404`.

---

## Päivitä agentti

`PUT /agents/{agentId}` — lähetä vain ne kentät, joita haluat muuttaa; kaikki muu jätetään ennalleen.

Sisäkkäisiä asetuksia voidaan käsitellä lehti kerrallaan pisteellä erotetulla avaimella, joten `"availability.monday"` muuttaa vain maanantain ja jättää muun viikon ennalleen.

**Huomautuksia**

- Jos haluat muuttaa, mihin varattavaan tapahtumatyyppiin agentti tekee varauksia, lähetä `event_id` (tapahtuman tunnus tai `null` sen tyhjentämiseksi). Lähetä `event_ids` taulukon kanssa linkittääksesi useita kerralla – ensimmäisestä tulee ensisijainen ja `[]` poistaa kaikkien linkitykset. `event_id` ja `event_ids` ovat toisensa poissulkevia, eikä `event`-kenttää itsessään voi kirjoittaa suoraan.
- `enable_bookings` on oltava todellinen totuusarvo (boolean), ja `booking_provider` on oltava jokin seuraavista: `default`, `zenchef`, `formitable`, `opentable`, `thefork`.
- Omistajuus- ja identiteettikentät jätetään huomiotta, samoin kuin sisäinen suoritustila (luonti- ja optimointiedistyminen).
- **Reititystä ei määritetä tässä.** Käytä `PUT /entry-points/channel-defaults`-kohtaa tehdäksesi agentista kanavan vastaaja, `POST /agents/{agentId}/entry-points`-kohtaa avainsana- ja kommenttisäännöille ja `PATCH /agents/{agentId}/active`-kohtaa sen keskeyttämiseen tai jatkamiseen.

**cURL**

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Tyhjä runko palauttaa `400` ja `"No fields to update"`.

---

## Päivitä botin asetukset

`PUT /agents/{agentId}/bot-config` – rajattu tapa muuttaa vain keskusteluasetuksia.

Agentilla ei ole erillistä bottiosiota: sen asetukset sijaitsevat suoraan agentissa, joten kenttien nimet ovat tässä samat, jotka lähettäisit kohteeseen `PUT /agents/{agentId}`. Tämä päätepiste on olemassa turvallisena ja keskitettynä tapana muuttaa muutamia niistä. Vähintään yksi kenttä on pakollinen.

| Kenttä | Kuvaus |
|---|---|
| `instructions` | Ensisijaiset ohjeet, jotka ohjaavat, miten agentti puhuu yhteyshenkilöille. |
| `rules` | Tiukat säännöt, joita sen on aina noudatettava. |
| `goal` | Lopputulos, jota sen tulisi tavoitella jokaisessa keskustelussa. |
| `personality` | Äänensävy ja persoonallisuuden kuvaus. |
| `language` | Kieli, jolla agentti vastaa. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` tai `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` tai `mini`. |
| `max_messages` | Agentin viestien enimmäismäärä keskustelua kohden. |
| `alert_human_when` | Milloin agentin tulisi hälyttää ihmistiimin jäsen. |
| `ai_transparency` | Ilmoittaako agentti olevansa tekoäly. |

> **Kenttien nimien on oltava tässä selkeitä nimiä** – kirjaimia, numeroita, alaviivoja ja yhdysviivoja. Pisteellisiä polkuja ei hyväksytä tässä päätepisteessä (toisin kuin `PUT /agents/{agentId}`), joten `bot.goal` hylätään virheellä `400`.

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

Pitkä teksti kuluttaa tilauksesi sallimaa konfiguraatiokokoa, joten erittäin laaja ohjeistus voidaan hylätä virheellä `400`.

---

## Aseta aktiiviset tunnit

`PUT /agents/{agentId}/active-hours` – tunnit, joiden aikana agentti vastaa automaattisesti. Näiden ikkunoiden ulkopuolella se pysyy hiljaa.

Lähetä `availability`-objekti, jonka avaimina ovat viikonpäivät (`monday`–`sunday`). Jokainen päivä ottaa yhden aikaikkunan tai listan ikkunoita 24 tunnin `HH:MM`-muodossa. Pois jätetyt päivät säilyttävät aiemmat asetuksensa, ja kaikki avaimet, jotka eivät ole viikonpäiviä, hylätään – joten kirjoitusvirhe ei voi jäädä huomaamatta.

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Virheellinen viikonpäiväavain palauttaa `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Keskeytä tai jatka agentin toimintaa

`PATCH /agents/{agentId}/active` — kytkee agentin päälle tai pois päältä. Keskeytetty agentti säilyttää kaikki asetuksensa, mutta lakkaa vastaamasta välittömästi; jatkaminen astuu voimaan heti.

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

`active` on oltava totuusarvo (boolean) – mikä tahansa muu palauttaa `400` ja `"active (boolean) is required"`.

---

## Agentin kopioiminen

`POST /agents/{agentId}/duplicate` — luo kopion, jonka asetukset säilyvät. Kopio ei lähetä mitään, ennen kuin osoitat sille kanavan tai sisääntulopisteen (Entry Point).

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**Vastaus** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Kopio lasketaan osaksi tilauksesi agenttikiintiötä aivan kuten tyhjästä luotu agentti, joten pyyntö hylätään virheellä `403`, jos tilin kiintiö on täynnä.

---

## Kopioi agentti alitilille (toimistot)

`POST /subaccounts/agents/copy` — kopioi agentin toimistotililtäsi (tai yhdeltä alitililtäsi) toiselle alitilille. Se kopioi syvällisesti kaikki riippuvuudet, jotta kopio toimii itsenäisesti kohdetilillä. Tämä on kutsu pääagentille, jonka haluat olevan jokaisen uuden asiakkaan lähtökohtana. Se korvaa vanhentuneen `POST /subaccounts/campaigns/copy`-kutsun.

Tämä päätepiste nimeää molemmat tilit itse, joten se ei vaadi `sub_account_id`-parametria. Se edellyttää toimiston API-avainta, jolla on muokkausoikeudet tiiminhallinta-alueella.

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `agentId` | Kyllä | Kopioitava agentti. Sen on kuuluttava toimistotilillesi tai yhdelle alitileistäsi. |
| `targetUserId` | Kyllä | Alitili, johon se kopioidaan. |
| `newName` | Ei | Kopion nimi. Oletuksena lähtöagentin nimi. |
| `copyFaqs` | Ei | Kopioi myös UKK- ja tietokantalähteet. Oletuksena `true`. |
| `copyCustomFunctions` | Ei | Kopioi myös mukautetut funktiot ja MCP-palvelimet. Oletuksena `false`. |

Mediakirjasto kopioituu aina mukana. Lähdetilin yhteystiedot, WhatsApp-mallit ja yhdistetyt sosiaalisen median julkaisut eivät koskaan kopioidu.

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/agents/copy" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "ag7HkQ2ZpLxR3mNb",
    "targetUserId": "abc123def456",
    "newName": "Inbound Instagram Leads",
    "copyFaqs": true
  }'
```

**Vastaus** (`200`)

```json
{
  "success": true,
  "data": {
    "agent_id": "ag9WsX3cRfV6tGyH",
    "shell_campaign_id": null,
    "message": "Agent copied successfully",
    "counts": { "agents": 1, "faqs": 12, "kbSources": 2, "customFunctions": 0, "mcpServers": 0, "mediaItems": 3 }
  }
}
```

`data.agent_id` on uusi agentti kohdetilillä. Kopio saapuu **keskeytettynä** (`active: false`) ilman reititystä, joten se ei voi vastata kenellekään ennen kuin jatkat sen toimintaa [`PATCH /agents/{agentId}/active`](#pause-or-resume-an-agent)-kutsulla ja osoitat asiakkaan kanavat siihen [`PUT /entry-points/channel-defaults`](entry-points.md#point-a-channel-at-an-agent)-kutsulla. [API for Agencies](../agency/api-for-agencies.md#worked-example-ship-a-template-agent-into-every-new-client) -sivulla käydään läpi kaikki kolme kutsua. Jos jokin epäonnistuu kesken kaiken, kaikki kohdetilille jo luodut tiedot peruutetaan.

| Tila | Milloin |
|---|---|
| `400` | `agentId` tai `targetUserId` puuttuu. |
| `403` | Avain ei ole toimiston avain tai kohdetili ei ole yksi sen alitileistä. |
| `404` | Agenttia ei ole olemassa tai se kuuluu toimistosi ulkopuoliselle tilille. |

---

## Agentin poistaminen

`DELETE /agents/{agentId}`

Poistaminen hylätään, jos agentti on yhä liitettynä johonkin, joka lakkaisi toimimasta ilman sitä – esimerkiksi lähetykseen, sisääntulopisteeseen tai (vanhemmilla tileillä) kampanjaan. Vastaus listaa estävät tekijät, jotta voit irrottaa ne ensin ja yrittää uudelleen.

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**Estetty** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## Luonnokset: tarkista muutokset ennen niiden julkaisua

Muokkausohjelmassa tehdyt muutokset ja kaikki [Optimoi tekoälyllä](#optimize-an-agent-with-ai) -toiminnon tuottamat uudelleenkirjoitukset tallennetaan **julkaisemattomana luonnoksena**, kunnes julkaiset ne. Siihen asti käytössä oleva agentti vastaa nykyisillä asetuksillaan.

### Julkaise luonnos

`POST /agents/{agentId}/publish-draft` — siirtää luonnoksen käytössä olevaksi konfiguraatioksi ja tyhjentää luonnoksen samassa vaiheessa.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` listaa asetukset, jotka siirtyivät luonnoksesta käytössä olevalle agentille, jotta voit nähdä, mikä muuttui.

> **Varmista ennen tämän kutsumista, että luonnos on olemassa.** Sellaisen agentin julkaiseminen, jolla ei ole luonnosta, ei ole tuettu toiminto, ja se palauttaa tällä hetkellä virheen `500` yleisellä viestillä, ei tarkalla virheilmoituksella. Jos haluat hylätä luonnoksen, käytä alla olevaa hylkäämistoimintoa.

### Hylkää luonnos

`POST /agents/{agentId}/discard-draft` — hylkää luonnoksen ja jättää aktiivisen konfiguraation täysin ennalleen. Turvallinen kutsua, kun luonnosta ei ole; mitään ei tapahdu.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## Agentin optimointi tekoälyllä

`POST /agents/{agentId}/optimize` — kirjoittaa Agentin konfiguraation uudelleen palautteesi perusteella ("se tarjoaa jatkuvasti alennuksia", "vastaukset ovat liian pitkiä") ja tallentaa uudelleenkirjoituksen **luonnoksena** sen sijaan, että se julkaistaisiin heti.

Lähetä joko `user_feedback` (yksinkertainen ohje) tai, kun reagoit tiettyyn huonoon vastaukseen, `thumbs_down_feedback` yhdessä virheellisen `thumbs_down_message` kanssa. Ainakin toisessa näistä on oltava tekstiä.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**Vastaus** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Työ suoritetaan taustalla ja kutsu palauttaa vastauksen välittömästi. Lue Agentti `GET /agents/{agentId}`-kutsulla ja tarkkaile `optimize_run.status`-tilaa; kun se palaa tilaan `Draft`, uudelleenkirjoitus odottaa Agentin luonnoksena. Tarkista se ja julkaise tai hylkää se.

Vain yksi suoritus kerrallaan per Agentti — toinen kutsu samanaikaisesti palauttaa `409`. Tämä kuluttaa tekoälypisteitä.

---

## Tunnistesäännöt

Tunnistesääntö koostuu tunnisteesta ja kuvauksesta siitä, milloin se pätee. Keskustelun aikana Agentti lukee kuvauksen ja lisää tunnisteen yhteyshenkilölle, kun se sopii tilanteeseen. Näin tunnisteisiin perustuvat automaatiot käynnistyvät.

**Sääntöobjekti**

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `name` | Kyllä | Lisättävä tunniste, esimerkiksi `hot-lead`. |
| `description` | Ei | Milloin Agentin tulisi lisätä se, kirjoitettuna ohjeena, jota se noudattaa. |
| `webhook` | Ei | URL-osoite, jota kutsutaan, kun Agentti lisää tämän tunnisteen. |
| `ai_can_remove` | Ei | Voiko Agentti myös poistaa tunnisteen. Oletusarvo on `false`. |
| `tag_id` | Ei | Tililläsi olevan olemassa olevan tunnisteen tunnus, johon sääntö linkitetään. Ilman tätä sääntö linkittyy samannimiseen tunnisteeseen ja luo sen, jos sitä ei ole — joten jokaista sääntöä voidaan myöhemmin käsitellä tunnisteen tunnuksella. |

### Lisää tunnistesääntö

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### Korvaa tunnistesääntö

`PUT /agents/{agentId}/tags/{tagId}` — sääntö löytyy polussa olevan tunnisteen (tag id) perusteella ja **korvataan kokonaan**, ei yhdistetä, joten lähetä koko sääntö sen sijaan, että lähettäisit vain muuttamasi osan. Tunniste, johon se osoittaa, säilyy, vaikka jättäisit `tag_id` pois, joten muokkaus ei voi irrottaa sääntöä tunnisteestaan.

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### Poista tunnistesääntö

`DELETE /agents/{agentId}/tags/{tagId}` — Agentti lakkaa käyttämästä kyseistä tunnistetta. Itse tunniste ja kaikki yhteystiedot, joilla se on jo käytössä, säilyvät ennallaan.

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

Molemmat päätepisteet palauttavat `404`, kun Agenttia ei ole olemassa **tai** kun sillä ei ole sääntöä kyseiselle tunnisteelle.

### Luo tunnistejoukko tekoälyllä

`POST /agents/{agentId}/tags/generate` — suunnittelee koko sääntöjoukon (tunnisteiden nimet ja kunkin takana oleva "käytä kun…" -muotoilu) lukemalla Agentin omat ohjeet ja tavoitteen.

| Kenttä | Kuvaus |
|---|---|
| `mode` | `merge` (oletus) säilyttää Agentilla jo olevat säännöt ja lisää niitä. `replace` suunnittelee joukon alusta alkaen. |

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**Vastaus** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

Työ suoritetaan taustalla. Lue Agentti ja seuraa `tag_generation.status`; säännöt päätyvät Agentin `tags`-kohtaan. Vain yksi ajo kerrallaan per Agentti (`409` muussa tapauksessa), ja se käyttää tekoälypisteitä.

---

## Tietolähteet

Tietolähteet ovat sivuja ja asiakirjoja, jotka alusta on lukenut puolestasi. Kun liität sellaisen Agenttiin, se voi vastata kyseisen sisällön perusteella.

**Mistä lähdetunnisteet tulevat.** Lisää sisältöä tietokannan päätepisteillä — `POST /kb-sources/url` sivulle, `POST /kb-sources/file` asiakirjalle, `POST /kb-sources/bulk-import` koko sivustolle. Ne palauttavat `source_id`-tunnisteen, jota voit kysellä `GET /kb-sources/{sourceId}`-toiminnolla, kunnes se on valmis. `POST /kb-sources/url` hyväksyy myös `autoLinkToAgentId`-parametrin, joka liittää lähteen Agenttiin heti tuonnin valmistuttua, joten voit ohittaa alla olevan liittämiskutsun.

### Liitä tietolähteitä

`POST /agents/{agentId}/kb-sources` — lähetä `kb_source_ids` ja luettelo liittääksesi koko joukon yhdellä kutsulla (mitä haluat sivuston indeksoinnin jälkeen), tai `kb_source_id` yksittäiselle lähteelle. Lähetä jompikumpi. Jo liitetyn kohteen liittäminen ei muuta mitään.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**Vastaus** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

### Irrota tietolähteitä

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` yhdelle tai `POST /agents/{agentId}/kb-sources/bulk-remove` `kb_source_ids`-parametrilla useammalle. Massapoisto on `POST`, koska tunnusluettelo kulkee pyynnön rungossa.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

Itse lähteitä ei poisteta, ja ne pysyvät muiden agenttiesi käytettävissä. Sellaisen kohteen irrottaminen, jota ei ole liitetty, ei muuta mitään.

### Usein kysytyt kysymykset (FAQ)

Usein kysyttyjä kysymyksiä hallitaan niiden omissa päätepisteissä ja linkitetään sieltä agenttiin: `POST /faqs/{faqId}/link` `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`-parametrilla ja `POST /faqs/{faqId}/unlink`, kun haluat poistaa linkityksen. FAQ voi olla usean eri agentin jaettavissa. Katso [FAQs API](faqs.md).

> FAQ-kysymyksiä käyttävät vain ne agentit, joihin ne on linkitetty – pelkkä luominen ei riitä.

---

## Työkalut

### Mukautetut funktiot

`POST /agents/{agentId}/custom-functions` mahdollistaa sen, että agentti voi kutsua mukautettuja funktioitasi keskustelujen aikana. Vain samaan tiliin kuuluvia funktioita voidaan liittää, ja jo liitetyn funktion liittäminen uudelleen ei muuta mitään.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` irrottaa sen. Itse funktiota ei poisteta, ja se pysyy muiden agenttiesi käytettävissä.

Hallitse itse funktioita kohdassa `/custom-functions` – katso [Mukautetut funktiot](../ai-automation/custom-functions.md), jos haluat tietää, mitä ne ovat.

### MCP-palvelimet

MCP-palvelin on valmis työkalupaketti, jonka agenttisi voi löytää ja jota se voi kutsua itsenäisesti – katso [Yhdistä MCP-palvelimet bottiisi](../ai-automation/mcp-servers.md). Palvelimet rekisteröidään tilille kerran, minkä jälkeen ne liitetään niihin agentteihin, joiden tulee niitä käyttää.

> MCP-palvelimet edellyttävät **mukautetut funktiot** -ominaisuutta tilauksessasi. Ilman sitä tilitason `/mcp-servers`-päätepisteet palauttavat `403`. Jo rekisteröidyn palvelimen liittäminen agenttiin ei ole rajoitettua.

#### Rekisteröi palvelin

`POST /mcp-servers`

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `name` | Kyllä | Palvelimen nimi. |
| `url` | Kyllä | Palvelimen osoite. On oltava tavoitettavissa julkisesta internetistä. |
| `auth_type` | Ei | `header` (oletus) staattiselle todennusotsikolle tai `oauth2`. |
| `auth_header_name` | Ei | Otsikko, jossa tunnistetiedot lähetetään. Oletus on `Authorization`. |
| `auth_header_value` | Ei | Itse tunnistetiedot. Ei palauteta koskaan vastauksissa. |
| `enabled` | Ei | Onko palvelin agenttien käytettävissä. Oletus on `true`. |
| `enabled_tools` | Ei | Työkalujen nimien sallittujen luettelo. `null` tarkoittaa, että kaikki palvelimen tarjoamat työkalut ovat käytössä. |
| `tool_policies` | Ei | Työkalukohtaiset rajoitukset työkalun nimen mukaan – kuinka usein työkalu voi aktivoitua, tulosten välimuisti ja vain luku -ohitus. Lähetä `null` tyhjentääksesi ne kaikki. |

```bash
curl -X POST "https://api.dmchamp.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**Vastaus** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

Tallennuksen yhteydessä alusta yhdistää palvelimeen ja tallentaa välimuistiin sen tarjoamien työkalujen luettelon. **Palvelin, johon ei saada yhteyttä, tallentuu silti**, syy näkyy kohdassa `last_error` ja työkaluluettelo on tyhjä – voit siis rekisteröidä palvelimen ensin ja korjata yhteyden myöhemmin.

`auth_type`, jonka arvo on `oauth2`, tallentaa rekisteröinnin `oauth_connected: false`-tunnisteella ilman työkaluja: tunnusta ei vielä ole. OAuth-palvelimen valtuuttaminen vaatii kirjautumisen selaimella ja se tehdään hallintapaneelista, ei API:n kautta.

#### Palvelimien luettelointi, päivitys ja poisto

- `GET /mcp-servers` – jokainen rekisteröity palvelin, uusimmat ensin, kohdassa `servers`.
- `PUT /mcp-servers/{serverId}` – lähetä vain muutettavat tiedot. URL-osoitteen tai todennuskenttien muuttaminen testaa yhteyden uudelleen ja päivittää välimuistissa olevan työkaluluettelon.
- `DELETE /mcp-servers/{serverId}` – poistaa rekisteröinnin ja linkityksen kaikista agenteista ja kampanjoista, joissa se oli käytössä.

```bash
curl "https://api.dmchamp.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**Salaisuuksia ei palauteta koskaan.** Vastaukset sisältävät `auth_header_value_set`-kentän (`true`/`false`-lippu, joka kertoo arvon olevan tallennettu) tunnistetietojen sijaan, ja OAuth-tunnukset sekä asiakassalaisuudet pysyvät palvelimen puolella. Kaikki muu palautetaan: `name`, `url`, `enabled`, `auth_type`, `auth_header_name`, `tools`, `enabled_tools`, `tool_policies`, `oauth_connected`, `tools_cached_at`, `last_connected_at`, `last_error`, `created_at`, `updated_at`.

#### Yhteyden testaaminen

`POST /mcp-servers/test-connection` – yhdistää palvelimeen ja luettelee sen työkalut. Kaksi tapaa kutsua sitä:

- `server_id`-parametrin kanssa – testaa **tallennetun** konfiguraation ja päivittää sen välimuistissa olevan työkaluluettelon;
- sisäisellä `url`-määrityksellä (sekä `auth_header_name` / `auth_header_value`) – tallennusta edeltävä testi, joka ei tallenna mitään.

```bash
curl -X POST "https://api.dmchamp.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**Vastaus** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

Yhteysvirhe **ei** ole HTTP-virhe – saat `200`-vastauksen, jossa on `success: false` ja `error`, joka kuvaa virheen syyn, jotta voit näyttää sen käyttäjän muokkaaman kentän vieressä.

#### Palvelimen liittäminen agenttiin

Palvelimen rekisteröinti ei anna millekään agentille pääsyä siihen. Liitä se:

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**Vastaus** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` irrottaa sen uudelleen. Itse palvelinta ei poisteta, ja se pysyy muiden agenttiesi käytettävissä. Sellaisen kohteen liittäminen tai irrottaminen, joka on jo kyseisessä tilassa, ei muuta mitään.

---

## Mediakirjasto

Mediakirjasto sisältää tiedostot, joita agentti voi lähettää keskustelun aikana – valikon, hinnaston tai tuotekuvan. Agentilla voi olla enintään **50 kohdetta**.

### Listaa media

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**Vastaus** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

Agentille tallennetut kohteet näkyvät ensin, ja niiden jälkeen vanhemmat kohteet, jotka on yhä tallennettu kampanjaan, josta Agentti on luotu; `media_home` (`agent` tai `campaign`) kertoo, kumpi on kyseessä. Kunkin ryhmän sisällä uusin näkyy ensimmäisenä.

> **`media_url` vanhenee 7 päivän kuluttua.** Se on tiedoston latauslinkki, joka luotiin tiedoston lataushetkellä – käsittele vanhaa linkkiä vanhentuneena pikemminkin kuin rikkinäisenä, ja lue lista uudelleen saadaksesi tuoreen linkin.

### Lataa mediaa

`POST /agents/{agentId}/media-library` — tiedosto ladataan sisäisesti base64-muodossa, enintään **10 MB**. Kutsu palautuu vasta, kun tiedosto on tallennettu, joten varaa hieman enemmän aikaa kuin tavalliselle pyynnölle. Huomaa, että tämä runko käyttää camelCase-kenttien nimiä.

| Kenttä | Pakollinen | Kuvaus |
|---|---|---|
| `base64Data` | Kyllä | Tiedoston sisältö, base64-koodattuna, ilman data-URL-etuliitettä. |
| `mimeType` | Kyllä | Tiedoston MIME-tyyppi. |
| `fileName` | Kyllä | Alkuperäinen tiedostonimi, jota käytetään tallennetun tiedoston nimeämiseen. |
| `title` | Ei | Kirjastossa näkyvä lyhyt nimi. |
| `description` | Ei | Ohje "milloin Agentin tulisi lähettää tämä". |
| `sendMessage` | Ei | Suositeltu sanamuoto, jonka Agentti sanoo lähettäessään kohteen. Rajattu 500 merkkiin. |
| `maxSendsPerConversation` | Ei | Kuinka monta kertaa se voidaan lähettää samalle yhteyshenkilölle yhden keskustelun aikana. Oletusarvo on `1`. |
| `sendAsVoiceNote` | Ei | Vain äänitiedostot – tallenna tiedosto WhatsApp-ääniviestinä. Ohitetaan muiden tiedostotyyppien kohdalla. |

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

Kaksi asiaa tapahtuu automaattisesti: animoitu GIF muunnetaan videoksi, jotta se toistuu kaikissa kanavissa, ja alusta kirjoittaa lyhyen yhteenvedon tiedoston sisällöstä, jotta Agentti tietää, milloin se sopii käytettäväksi.

`400` kattaa puuttuvat kentät, tukemattoman tiedostotyypin, tyhjän tai liian suuren tiedoston sekä 50 kohteen rajan ylittämisen. `403` tarkoittaa, että mediakirjasto on kytketty pois päältä tililtä.

### Päivitä mediakohde

`PATCH /agents/{agentId}/media-library/{itemId}` — vain metatiedot. Itse tiedostoa ei voi korvata; lataa uusi kohde ja poista vanha. Tämä runko käyttää snake_case-muotoa: `title`, `description`, `send_message`, `max_sends_per_conversation` (ei-negatiivinen kokonaisluku tai `null` rajan poistamiseksi).

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**Vastaus** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### Poista mediakohde

`DELETE /agents/{agentId}/media-library/{itemId}` — poistaa kohteen ja sen tallennetun tiedoston. Jo poistetun kohteen poistaminen onnistuu ja palauttaa `deleted: false`, joten kutsu on turvallista yrittää uudelleen.

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## Luo jatkoviestit

`POST /agents/{agentId}/template-generation` — kirjoittaa Agentin jatkoviestit puolestasi (muistutukset, joita se lähettää keskustelun hiljentyessä) sen perusteella, mitä varten Agentti on olemassa.

| Kenttä | Kuvaus |
|---|---|
| `type` | `all` (oletus) kirjoittaa koko joukon. `cold_only` kirjoittaa vain viestit yhteyshenkilöille, jotka eivät koskaan vastanneet. |

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

Tämä palautuu kahdella tavalla, ja `target`-kenttä kertoo kumpi on kyseessä:

- **`target: "agent"` ja `200`** — viestit kirjoitettiin puhelun aikana ja tulos on kohdassa `data`. Lue ne Agentin `follow_up_config`-kohdasta. Tämä on tavallinen tapaus.
- **`target: "campaign"` ja `202`** — työ asetettiin jonoon kampanjassa, jonka nimi on `campaign_id`. Seuraa kyseisen kampanjan `template_generation_status`-kohtaa, kunnes se valmistuu.

`cold_only` vaatii lähtevän kampanjan, ja se hylätään virheellä `409` (`reason: "cold_only_requires_campaign"`), jos Agentilla ei ole sellaista. `403` tarkoittaa, että automaattiset jatkotoimenpiteet eivät ole päällä tilillä. Tämä käyttää tekoälypisteitä, ja `400` virheellä `"Insufficient credits."` tarkoittaa, että pisteet ovat loppu.

---

## Keskustelujen reitittäminen Agentille

Agentti vastaa vain niihin keskusteluihin, jotka **sisääntulopiste** (Entry Point) sille lähettää. Ennen kuin kanavalla on sellainen, ensimmäinen viesti henkilöltä, jolle et ole koskaan puhunut, tallennetaan kyllä, mutta mikään ei poimi sitä eikä avustaja vastaa.

| Mitä haluat tehdä | Kutsu |
|---|---|
| Tee Agentista koko kanavan vastaaja | `PUT /entry-points/channel-defaults` ja `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Lisää tarkempi sääntö (avainsanat, kommentit, uudet seuraajat) | `POST /agents/{agentId}/entry-points` |
| Näe yhteen Agenttiin osoittavat säännöt | `GET /agents/{agentId}/entry-points` |
| Jätä kanava ilman vastaajaa | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Listaa Agentin sisääntulopisteet

`GET /agents/{agentId}/entry-points` — reitityssäännöt, jotka lähettävät keskusteluja tälle Agentille, uusimmasta alkaen. Sekä nykyiset että poistetut säännöt palautuvat; poistetussa säännössä on `enabled: false`.

```bash
curl "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

Jos haluat lukea koko tilin kanavien oletusasetukset, mukaan lukien kanavan, joka on tarkoituksella asetettu ilman vastaajaa, lue sen sijaan `GET /entry-points/channel-defaults`.

### Luo sisääntulopiste

`POST /agents/{agentId}/entry-points` — polussa oleva Agentti voittaa aina, joten sääntöä ei voi koskaan luoda eri Agentille kuin se, joka on URL-osoitteessa.

| `type` | Mitä se tekee |
|---|---|
| `channel_default` | Agentti vastaa jokaiselle uudelle yhteyshenkilölle listatuilla kanavilla. Suosi tätä varten `PUT /entry-points/channel-defaults`-kohtaa — se poistaa edellisen vastaajan puolestasi, mitä toisen oletusasetuksen luominen tähän ei tee. |
| `keyword` | Agentti ottaa ohjat, kun ensimmäinen viesti sisältää jonkin `match_config.keywords`-kohdan arvoista. Vähintään yksi avainsana vaaditaan. |
| `instagram_comment` / `facebook_comment` | Agentti vastaa julkaisujesi kommentteihin. Vastaavan kanavan on oltava listattuna kohdassa `channels`. |
| `instagram_follower` | Agentti tervehtii uusia seuraajia. |

`channels` on pakollinen ja kertoo, mitä kanavia sääntö koskee — esimerkiksi `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` tai `custom_channel`. Uudet säännöt ovat käytössä, ellet toisin määritä.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**Vastaus** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**Mikä sääntö voittaa, jos useampi voisi:** käynnissä oleva keskustelu tai manuaalinen määritys pitää Agentin, joka sillä jo on; muussa tapauksessa avainsanasäännöt voittavat kommenttisäännöt, jotka voittavat seuraajasäännöt, ja kanavan oletusasetus on viimeinen keino. Sen, päättävätkö nämä säännöt vielä mitään tilillä, raportoi `GET /entry-points/routing-status`.

Tämä on lyhyt versio. [Entry Points API](entry-points.md) -opas kattaa koko tikapuu-, kommentti- ja seuraajasäännöt, yhden agentin per WhatsApp-numero sekä säännön muuttamisen tai poistamisen. Katso [Entry Points](../ai-agents/entry-points.md) konseptia varten ja [Channels API](channels.md) itse kanavan yhdistämistä varten.

---

## AI-agenttien API-virheet

Agenttien päätepisteet palauttavat vakiomuotoisen virhekuoren:

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| Tila | Milloin se tapahtuu agentin päätepisteessä |
|---|---|
| `400` | Pakollinen kenttä puuttuu tai on virheellinen — tyhjä päivityksen runko, sallitun luettelon ulkopuolinen arvo (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), muu kuin arkipäiväavain `availability`-kohdassa, pisteellinen kentän nimi `bot-config`-kohdassa tai virheellinen tunniste polussa. |
| `403` | Tili ei saa käyttää lähettämääsi asetusta, olet saavuttanut tilauksesi agenttirajan tai jokin tämän päätepisteen tarvitsema ominaisuus (mediakirjasto, jatkotoimet, mukautetut funktiot MCP-palvelimille) on pois päältä. Muutos, joka ylittää tilauksesi salliman konfiguraatiokoon, hylätään virheellä `400`. |
| `404` | Agenttia, tunnistesääntöä, mediatiedostoa tai MCP-palvelinta ei löytynyt — se joko ei ole olemassa tai kuuluu toiselle tilille. |
| `409` | Jotain on jo käynnissä tai tiellä: optimointi tai tunnisteiden luonti on käynnissä, agentti on edelleen liitettynä lähetykseen, sisääntulopisteeseen tai kampanjaan, tai `cold_only`-toimintoa pyydettiin ilman lähtevää kampanjaa. |

Jaetut koodit, joita jokainen päätepiste voi palauttaa — `401`, `403` (tilauksesi ei sisällä API-käyttöoikeutta), `429` (nopeusrajoitus) ja `500` — on lueteltu uudelleenyritysohjeiden kera kohdassa [Virheet ja sivutus](errors-and-pagination.md).

> **Huomautus tutkijasta.** `/agents`-päätepisteet ovat julkaistussa OpenAPI-määrityksessä, joten voit selata niiden tarkkoja kenttiä ja suorittaa live-pyyntöjä [API-viitteessä](reference.md). Tilatason `/mcp-servers`-päätepisteet ovat myös määrityksessä, joten voit tutkia niitä myös siellä.

::: master-only
Määrityksessä oleminen tarkoittaa myös sitä, että agenttien päätepisteet — ja `/mcp-servers`-päätepisteet — näkyvät työkaluina kaikille tekoälyavustajille, jotka [yhdistät MCP:n kautta](../integrations/connect-ai-clients.md).
:::

---

## Aiheeseen liittyvää

- [AI-agentit](../ai-agents/ai-agents.md) — mitä agentti tarkoittaa selkokielellä.
- [Sisääntulopisteet](../ai-agents/entry-points.md) — miten keskustelut ohjataan agentille.
- [UKK-API](faqs.md) — rakenna ja linkitä tieto, johon agenttisi vastaa.
- [Kanavien API](channels.md) — yhdistä kanavat, joissa agentti vastaa.
- [Yhdistä MCP-palvelimet bottiisi](../ai-automation/mcp-servers.md) · [Mukautetut funktiot](../ai-automation/custom-functions.md)
- [API-viite](reference.md) — täydellinen interaktiivinen päätepisteiden tutkija.