# 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.youraiconnector.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).


---

## 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.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.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.youraiconnector.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` sulkevat toisensa pois, eikä `event`-kenttää itsessään voi kirjoittaa suoraan.
- `enable_bookings` on oltava totuusarvo (boolean), ja `booking_provider` on oltava jokin seuraavista: `default`, `zenchef`, `formitable`.
- Omistajuus- ja identiteettikentät jätetään huomiotta, samoin kuin sisäinen suoritustila (generoinnin ja optimoinnin edistyminen).
- **Reititystä ei aseteta tässä.** Käytä `PUT /entry-points/channel-defaults`-kohtaa määrittääksesi agentin vastaajaksi kanavalle, `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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.youraiconnector.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.youraiconnector.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ä.

---

## 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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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ä.


---

## 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.