# Automaatioiden API

Automaatio on työnkulku, joka koostuu vaiheista: yhdestä tai useammasta käynnistimestä, jotka aloittavat sen, sekä toiminnoista, ehdoista, viiveistä, tekoälyvaiheista ja muista osista, jotka on yhdistetty kaavioksi. Se on sama automaatio, jonka näet ja jota muokkaat [Automaatiot](../automations/automations.md)-sivulla. Tämä opas kattaa niiden lukemisen ja rakentamisen API:n kautta.

- **Perus-URL**: `https://api.dmchamp.com/v1`
- **Todennus**: API-avaimesi (katso [Todennus](authentication.md))
- **Kentät ja rungot**: jokainen parametri ja vastauskenttä löytyy [API-viitteestä](reference.md#tag/automations)
- **Virheet**: katso [Virheet ja sivutus](errors-and-pagination.md) sekä [Virheet](#errors) alta

> **Toimistot:** jokainen tämän sivun päätepiste hyväksyy `sub_account_id`-kyselyparametrin, joten voit lukea ja rakentaa asiakkaan automaatioita toimistoavaimellasi. `sub_account_id`, joka ei ole jokin asiakastileistäsi, palauttaa `404`. Katso [API toimistoille](../agency/api-for-agencies.md).

---

## Miten se toimii: ensin luonnos

API on rakennettu siten, ettei mikään käynnisty vahingossa.

1. **Lue luettelo.** `GET /automations/steps` listaa jokaisen käynnistimen, toiminnon ja vaihetyypin, jota voit käyttää, sekä kieliopin kaavion kirjoittamiseen (`graph_rules`).
2. **Luo luonnos.** `POST /automations` tallentaa automaation **pois päältä**. Mikään ei vielä käynnisty.
3. **Tarkista se.** Lue se takaisin, avaa se rakennustyökalussa (vastaus antaa sinulle sen `open_path`-tunnisteen) ja varmista, että tilin omistaja on nähnyt, mitä se tekee ja kenelle.
4. **Kytke se päälle.** `POST /automations/{automationId}/enable` on oma kutsunsa. Tämä on vaihe, joka saa todellisia asioita tapahtumaan: viestejä lähetetään, tietueita muutetaan, työkaluja annetaan tekoälyagentille.

Muokkaaminen ei koskaan muuta sitä, onko automaatio päällä vai pois päältä. Tämä tarkoittaa myös sitä, että **päällä** olevan automaation muokkaus astuu voimaan heti, suoraan käytössä olevaan automaatioon. Jos haluat muuttaa käynnissä olevaa automaatiota turvallisesti, poista se käytöstä, muokkaa sitä, tarkista se ja ota se uudelleen käyttöön.

Jokainen lähettämäsi kaavio käy läpi samat tarkistukset kuin rakennustyökalun pohja. Kaavio, jota se ei voi avata tai suorittaa, hylätään `400`-vastauksella, joka listaa tarkalleen, mitä on korjattava.

### Käyttöoikeudet

- Tilillä on oltava Automaatiot-ominaisuus. Ilman sitä jokainen tämän sivun kutsu palauttaa `403`.
- Tiimin jäsenen käyttöoikeudet noudattavat heidän **Automaatiot**-aluettaan [Tiimin hallinnassa](../settings/team-management.md): lukeminen (listaus, haku, vaiheet, suoritukset, kansiot) vaatii **Näytä**-oikeuden, ja kaikki, mikä muuttaa jotakin, vaatii **Muokkaa**-oikeuden.
- Asiakastilillä, jonka sopimukseen ei kuulu automaatioiden luominen ja muokkaaminen, kirjoituskutsut palauttavat `403`, aivan kuten sovelluksen rakennustyökalu.

---

## Päätepisteet

| Tehtävä | Metodi + polku | Selain |
|---|---|---|
| Listaa automaatiot | `GET /automations` | [Avaa API-viitteessä](reference.md#tag/automations/GET/automations) |
| Hae automaatio ja sen kaavio | `GET /automations/{automationId}` | [Avaa API-viitteessä](reference.md#tag/automations/GET/automations/{automationId}) |
| Lue vaiheluettelo | `GET /automations/steps` | [Avaa API-viitteessä](reference.md#tag/automations/GET/automations/steps) |
| Luo automaatio (luonnos) | `POST /automations` | [Avaa API-viitteessä](reference.md#tag/automations/POST/automations) |
| Päivitä automaatio | `PUT /automations/{automationId}` | [Avaa API-viitteessä](reference.md#tag/automations/PUT/automations/{automationId}) |
| Kytke päälle | `POST /automations/{automationId}/enable` | [Avaa API-viitteessä](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Kytke pois päältä | `POST /automations/{automationId}/disable` | [Avaa API-viitteessä](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Lue suoritushistoria | `GET /automations/{automationId}/runs` | [Avaa API-viitteessä](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Listaa kansiot | `GET /automations/folders` | [Avaa API-viitteessä](reference.md#tag/automations/GET/automations/folders) |
| Luo kansio | `POST /automations/folders` | [Avaa API-viitteessä](reference.md#tag/automations/POST/automations/folders) |
| Nimeä kansio uudelleen | `PUT /automations/folders/{folderId}` | [Avaa API-viitteessä](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Poista kansio | `DELETE /automations/folders/{folderId}` | [Avaa API-viitteessä](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Siirrä automaatio kansioon | `PUT /automations/{automationId}/folder` | [Avaa API-viitteessä](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Automaatioiden lukeminen

`GET /automations` palauttaa yhteenvedot (ei vaiheita), uusimmat ensin; `folder_id=none` listaa ne, jotka eivät ole kansiossa. `GET /automations/{automationId}` lisää täydellisen `graph`: jokaisen vaiheen (`nodes[]`) sen `kind`, `label`, `alias`, `action`, `params` ja `config` kanssa, sekä yhteydet (`edges[]`) `from`, `to` ja ehdon tai vastaavan jälkeen `branch` kanssa.

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY"
```

**Hyvä tietää**

- **`alias` on tapa, jolla myöhemmät vaiheet lukevat vaiheen tulosteen**, muodossa `${nodes.<alias>.<field>}`. Vaiheeseen, jolla ei ole tällaista, viitataan sen tunnuksella (id).
- `params` on säilytetty vanhempia lukijoita varten; `config` sisältää samat arvot ja enemmän (ehdon säännöt, tekoälyvaiheen kehotteen, viiveen keston, toiminnon slug-tunnisteen ja parametrit).
- **Salaisuudet on piilotettu.** Arvot, jotka näyttävät tunnistetiedoilta (webhook-salaisuudet, tunnisteet, API-avaimet, salasanat, otsikkoarvot), palautuvat muodossa `"[redacted]"`. Lähetä `"[redacted]"` takaisin muuttamattomana, niin tallennettu arvo säilyy.
- **Pitkät tekstit lyhennetään.** Yli 4 000 merkkiä pitkä teksti katkaistaan ja se päättyy ellipsiin. Jos lähetät kyseisen vaiheen takaisin, palauta ensin sen koko teksti.
- Jos automaatiopalveluun ei saada yhteyttä, saat `503`, et koskaan tyhjää listaa. Tyhjä lista tarkoittaa aina, ettei automaatioita ole.

### Vaiheluettelo

`GET /automations/steps` palauttaa kaiken, mistä automaatio voidaan rakentaa: 8 `node_kinds`, jokaisen käynnistimen asetuksineen `fields` ja `output_keys`, sisäänrakennetut `actions` parametreineen, `api_actions` (tämän API:n toiminnot, joita toimintovaihe voi kutsua), `graph_rules`-kieliopin ja `counts`. Tämä on se, mitä rakennustyökalu **tarjoaa**, ei se, mitä tili on rakentanut: tarkista tämä ennen kuin päättelet, ettei käynnistintä tai toimintoa ole olemassa.

- Ilman `q`-parametria sadat API-toiminnot palautuvat alueittain ryhmiteltyinä otsikkoina `api_actions_by_tag`-kohdassa, ja tasainen lista on tyhjä.
- `q`-parametrin (kirjainkoosta riippumaton sana) kanssa `api_actions` on tasainen lista osumista, rajoitettuna 60 kappaleeseen (`api_actions_truncated` kertoo milloin). Myös yhdistettyjen kolmannen osapuolen sovellusten toiminnot haetaan ja ne palautuvat `app_actions`-kohdassa: hae sovelluksen nimellä, esimerkiksi `q=hubspot`. Jokainen kertoo, onko tilillä kyseinen sovellus `connected`, ja `connected_apps` listaa yhdistetyt sovellukset. `app_actions_unavailable` on `true`, kun sovellustoimintoja ei voitu tällä kertaa hakea; muut listat ovat yhä täydellisiä.

---

## Luominen ja muokkaaminen

### Luo luonnos

```bash
curl -X POST "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price question auto-reply",
    "description": "Replies with the price list when someone asks about prices.",
    "graph": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger", "label": "Incoming message",
          "data": { "trigger": { "kind": "incoming_message", "message_filter_contains": "price" } } },
        { "id": "send_prices", "type": "action", "label": "Send message",
          "data": { "action": { "provider": "native", "slug": "SEND_MESSAGE",
            "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" } } } }
      ],
      "edges": [{ "source": "trigger_1", "target": "send_prices" }]
    }
  }'
```

```json
{ "success": true, "automation": { "id": "8d2c7f1e-…", "enabled": false, "…": "…" }, "draft": true, "open_path": "/automations/8d2c7f1e-…", "warnings": [] }
```

`draft: true` ja `enabled: false` ovat normaaleja, eivät virheitä: uusi automaatio on aina luonnos, kunnes otat sen käyttöön. `warnings` listaa asiat, joita rakennustyökalu ei voinut viimeistellä, lyhyinä otsikkoina (esimerkiksi `agent_function:not_linked`).

**Kaavion kirjoittaminen.** `graph_rules` luettelosta on täydellinen kielioppi. Lyhyesti:

- Jokaisella solmulla on `id` (yksilöllinen kaaviossa), `type` (yksi 8 [vaihetyypistä](#step-kinds)), valinnainen `label` ja sen asetukset `data`-kohdassa tyypin mukaan nimetyn avaimen alla (`data.trigger`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Automaatio tarvitsee vähintään yhden käynnistimen. Live-kielioppi sallii enintään 10, ja automaatio käynnistyy, kun mikä tahansa niistä laukeaa.
- Jokaisen muun vaiheen on oltava saavutettavissa käynnistimestä, eikä mikään yhteys saa johtaa takaisin aiempaan vaiheeseen.
- Ehdosta lähtevät reunat kantavat `sourceHandle` `true` tai `false`; silmukka `body` tai `done`; Vastausta odottava viive `replied` tai `timed_out`. Muilla reunoilla ei ole mitään.
- Toimintojen slug-tunnisteet ja parametrit tulevat luettelosta. **Älä koskaan arvaa tunnusta** (agentti, tunniste, lista, vaihe): etsi se ensin API:n avulla tai jätä kenttä `""`-arvoksi, jotta käyttäjä voi valita sen rakennustyökalussa.
- Sijainnit ovat valinnaisia; vaiheet, joilla ei ole sijaintia, asetellaan automaattisesti.
- Aiemmista vaiheista saadut arvot kirjoitetaan muodossa `${trigger.<field>}` ja `${nodes.<step>.<field>}`. Katso [Aiemman vaiheen tulosten käyttäminen](../automations/automations.md#using-what-an-earlier-step-returned) ja [Lausekkeet](../automations/automations.md#expressions).
- Kaavio hyväksytään kahdessa muodossa: rakennustyökalun omassa (yllä) ja siinä, jolla lukutoiminto vastaa (`kind`, `config`, `from`, `to`, `branch`). Voit siis lukea automaation, muuttaa vaihetta ja lähettää sen takaisin.
- **Luomista ei ole turvallista toistaa sokeasti.** Jos pyyntö aikakatkaistaan, listaa automaatiosi ennen kuin lähetät sen uudelleen, muuten saatat päätyä kahteen luonnokseen.

### Päivitä

`PUT /automations/{automationId}` muuttaa `name`, `description` ja/tai `graph` (vähintään yksi tai `400`). `graph` korvaa **koko** kaavion, joten työskentele aina tallennetun version pohjalta: lue se, tee tarvittavat muutokset ja lähetä koko kaavio takaisin.

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Price question auto-reply (EN)" }'
```

- **Säilytä jokaisen vaiheen `alias` täsmälleen sellaisena kuin sait sen.** Jos muutat tai poistat sen, kaikki kyseiseen vaiheeseen viittaava jää tyhjäksi. Katso [Vaiheiden nimeäminen](../automations/automations.md#naming-your-steps).
- **Jätä `"[redacted]"`-arvot ennalleen** ja **palauta lyhennetyt tekstit** (kolmella pisteellä päättyvä teksti oli katkaistu lukuhetkellä).
- Automaation tilaa (päällä/pois) ei muuteta tässä. Jos se on päällä, muokkauksesi astuu voimaan heti tallennuksen jälkeen. Kun se on päällä, muutosta, joka saisi automaation käynnistämään itsensä, ei hyväksytä: poista se ensin käytöstä.

### Käyttöönotto ja käytöstä poisto

`POST /automations/{automationId}/enable` kytkee automaation päälle, jolloin se suoritetaan käynnistimen perusteella tästä eteenpäin. Kutsu tätä vasta, kun tilin omistaja on nähnyt, mitä automaatio tekee ja kenelle, ja on antanut siihen suostumuksensa. Rakennustyökalu kieltäytyy kytkemästä päälle kaaviota, jota ei voi suorittaa (ei käynnistintä, silmukka, itseään käynnistävä vaihe), ja antaa `400`-vastauksen, jossa kerrotaan syy.

```bash
curl -X POST "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable?apiKey=YOUR_API_KEY"
```

`POST /automations/{automationId}/disable` keskeyttää sen: jo käynnissä olevat suoritukset viedään loppuun, mutta uusia ei aloiteta. Käytöstä poistaminen on aina sallittua. Kumpikaan kutsu ei vaadi runkoa (body).

---

## Suoritushistoria

`GET /automations/{automationId}/runs` palauttaa yhden automaation suoritukset, uusimmat ensin (`limit` 1–50, oletus 10): milloin kukin alkoi ja päättyi, mikä sen käynnisti, onnistuiko se ja virheilmoitus, jos se epäonnistui. Automaation lukeminen kertoo, mitä se **tekisi**; suoritushistoria kertoo, mitä se **teki**, ja se on ainoa tapa erottaa automaatio, joka ei ole koskaan käynnistynyt, sellaisesta, joka käynnistyy ja epäonnistuu joka kerta.

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?apiKey=YOUR_API_KEY&limit=20"
```

- `mode` on `live` todelliselle suoritukselle tai `safe` **turvalliselle suoritukselle** editorista. Turvallinen suoritus ei lähetä mitään, joten se ei ole todiste siitä, että automaatio toimii käytännössä.
- Tyhjä `runs`-luettelo on vastaus, ei puute. Vastaus sisältää tällöin `note`-kohdan: joko käynnistin ei ole koskaan lauennut tai automaatio on kytketty pois päältä.

---

## Kansiot

Kansiot vain ryhmittelevät automaatioita luettelossa. Ne eivät koskaan muuta automaation toimintaa tai sitä, onko se päällä. Katso [Automaatioiden järjestäminen kansioihin](../automations/automations.md#organizing-automations-in-folders).

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/folder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708" }'
```

- Kansioiden listaaminen palauttaa myös `unfiled_count`, eli kuinka monta automaatiota ei ole missään kansiossa.
- Kansion nimi on pakollinen, enintään 100 merkkiä, ja sen on oltava tilillä yksilöllinen (`409`, `code: "folder_name_taken"`). Voit myös sijoittaa automaation kansioon välittämällä `folder_id`-parametrin luonnin yhteydessä.
- Uudelleennimeäminen jättää automaatiot paikoilleen.
- **Kansion poistaminen poistaa vain kansion.** Sen sisältämät automaatiot siirtyvät pois kansioista ja jatkavat toimintaansa täsmälleen kuten ennenkin; vastaus kertoo, kuinka monta siirrettiin (`moved_to_no_folder`).
- Siirron yhteydessä `folder_id` on pakollinen; lähetä `null` poistaaksesi automaation kansiosta.

---

## Luettelo

### Vaihetyypit

| Tyyppi | Mitä se tekee |
|---|---|
| `trigger` | Käynnistää automaation, kun jotain tapahtuu. |
| `action` | Suorittaa yhden vaiheen: sisäänrakennetun toiminnon, API-toiminnon, yhdistetyn sovelluksen toiminnon, HTTP-pyynnön tai sähköpostin. |
| `condition` | Jakaa kulun säännön perusteella `true`- ja `false`-haaroihin. |
| `transform` | Suorittaa lyhyen koodinpätkän datan muokkaamiseksi vaiheiden välillä. |
| `ai` | Kysyy tekoälyltä kirjoittamallasi kehotteella. Se voi palauttaa tekstiä, erillisiä kenttiä tai valita yhden useista haaroista. |
| `delay` | Odottaa tietyn ajan tai odottaa kontaktin vastausta (aikakatkaisulla). |
| `loop` | Toistaa sisällään olevat vaiheet jokaiselle listan kohteelle. |
| `respond` | Palauttaa vastauksen webhook-kutsulle tai tekoälyagentin funktiokutsulle, joka käynnisti suorituksen. |

### Käynnistimet

Nämä ovat 40 käynnistintä, jotka luettelo tällä hetkellä sisältää, ryhmiteltynä samalla tavalla kuin rakentajassa. **Asetukset**-sarake sisältää käynnistimen omat asetusavaimet (`fields`), jotka rajaavat sen laukeamista. Jokainen käynnistin ottaa myös parametrit `respect_quiet_hours`, `run_hours`, `reentry` ja `stop_on_response`; katso [Automaatioasetukset](../automations/automations.md#automation-settings).

**Viestintä**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Saapuva viesti (`incoming_message`) | Kontakti lähettää viestin millä tahansa kanavalla. | `campaign` (rajoittaa yhteen tekoälyagenttiin), `channel`, `message_filter_contains` (avainsana), `message_filter_regex` (malli) |
| Vastaamaton puhelu (`missed_call`) | Joku soittaa johonkin WhatsApp Web -numeroistasi tai omaan tekstiviestinumeroosi, eikä kukaan vastaa. | `to_number` |
| Viesti toimitettu (`message_delivered`) | Kanava vahvistaa lähettämäsi viestin toimitetuksi. | `channel`, `agent` |
| Viestin lähetys epäonnistui (`message_failed`) | Lähettämäsi viesti ei tullut perille, sisältää virheen. | `channel`, `agent` |
| Viesti lähetetty (`message_sent`) | Mikä tahansa viesti lähtee tililtäsi: tekoälyn, sinun, joukkolähetyksen tai jatkotoimenpiteen kautta. Suodata se, tai se suoritetaan kaikille. | `channel`, `sent_by` |
| Jatkotoimenpide lähetetty (`follow_up_sent`) | Automaattinen jatkotoimenpide lähtee. | ei mitään |
| Jatkotoimenpide ohitettu (`follow_up_skipped`) | Jatkotoimenpide pidätettiin, koska sen lähetysehto ei täyttynyt. | ei mitään |
| Jatkotoimenpiteet valmiit (`follow_up_exhausted`) | Kontakti sai sarjan viimeisen jatkotoimenpiteen eikä mitään muuta ole jonossa. | ei mitään |
| Keskustelu suljettu (`conversation_closed`) | Keskustelu suljetaan, sisältäen tiedon päättymistavasta ja yhteenvedon. | `channel`, `agent` |
| Joukkolähetys valmis (`broadcast_completed`) | Joukkolähetys on valmistunut, sisältäen tiedon lähetettyjen ja epäonnistuneiden määrästä. | ei mitään |
| Liidin vastaus lajiteltu (`outreach_reply_labelled`) | Kylmän sähköpostiliidin vastaus on lajiteltu, esimerkiksi tilaan Kiinnostunut. | `label` |
| Skool-kommentti vastaanotettu (`skool_comment_received`) | Jäsen kommentoi Skool-julkaisua, jota jokin kommenttisäännöistäsi seuraa. | ei mitään |

**Yhteystiedot**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Uusi kontakti (`contact_created`) | Uusi henkilö ottaa yhteyttä ensimmäistä kertaa millä tahansa kanavalla, sekä tuontien, API:n ja käsin lisäämiesi kontaktien kohdalla. | ei mitään |
| Kontakti päivitetty (`contact_updated`) | Kontaktikenttä muuttuu. | `field` |
| Lisäämäsi kontaktit (`contact_added`) | Vain kontakteille, jotka lisäät tähän automaatioon itse Kontaktit-sivulta. Yksi suoritus per kontakti. | ei mitään |
| Tunniste lisätty (`tag_applied`) | Tunniste lisätään kontaktiin tekoälyagenttisi, henkilön, automaation tai tuonnin toimesta. | `tag_name`, `channel`, `applied_by` |
| Tunniste poistettu (`tag_removed`) | Tunniste poistetaan kontaktilta. | `tag_name`, `channel` |
| Skool-jäsen liittyi (`skool_member_joined`) | Joku liittyy omistamaasi tai hallinnoimaasi Skool-yhteisöön, sisältäen profiilin, vastaukset ja sopivuuspisteet. | `group_id`, `create_contact` |
| Skool-jäsen hyväksytty (`skool_member_qualified`) | Uuden Skool-jäsenen vastausten pisteet ylittävät kynnysarvosi. | `min_score` |

**Kaupat**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Kauppa luotu (`deal_created`) | Uusi kauppa lisätään johonkin putkistostasi. | `pipeline_id`, `stage_id` |
| Kaupan vaihe muuttui (`deal_stage_changed`) | Kauppa siirtyy eri vaiheeseen, nimeten vaiheen josta se lähti ja johon se saapui. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Kauppa päivitetty (`deal_updated`) | Kaupan kenttä muuttuu. | `field` |

**Tapaamiset**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Tapaaminen varattu (`appointment_booked`) | Uusi tapaaminen on varattu. | ei mitään |
| Tapaaminen peruttu (`appointment_cancelled`) | Varattu tapaaminen on peruttu. | ei mitään |
| Tapaaminen siirretty (`appointment_rescheduled`) | Varattu tapaaminen siirtyy toiseen ajankohtaan, näyttäen vanhan ja uuden ajan. | `event_id` |
| Ennen tapaamista (`appointment_upcoming`) | Asetettu aika ennen jokaista vahvistettua tapaamista, muistutuksia varten. Jopa viisi muistutusta per automaatio. | `offsets_minutes` |

**Tehtävät**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Tehtävä luotu (`task_created`) | Tehtävä on luotu. | `task_type` |
| Tehtävä suoritettu (`task_completed`) | Tehtävä on siirretty suoritettu-vaiheeseen. | ei mitään |

**Tili**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Alhainen saldo (`low_credit_balance`) | Saldosi laskee hälytyskynnyksen alapuolelle. | ei mitään |
| Kanava yhdistetty (`channel_connected`) | Yhden kanavasi yhdistäminen valmistuu. | `channel` |
| Kanava katkaistu (`channel_disconnected`) | Yksi kanavistasi katkeaa: uloskirjautuminen, linkityksen poisto tai yhteyskatkos. WhatsApp Web -numero, joka yhdistyy uudelleen itsestään, lasketaan vain, jos se on edelleen alhaalla 30 minuutin kuluttua. | `channel` |

**Toimisto**

| Käynnistin (`kind`) | Laukeaa kun | Asetukset |
|---|---|---|
| Alitili luotu (`sub_account_created`) | Uusi asiakastili luodaan hallintapaneelista, API:n kautta tai rekisteröitymissivultasi. | ei mitään |
| Alitilin toiminta (`sub_account_event`) | Jotain tapahtuu yhdellä asiakastileistäsi: saldo vähissä, kanavan yhdistyminen, suunnitelman muutos. | `event`, `threshold` |

**Yleiset ja sovellukset**

| Käynnistin (`kind`) | Aktivoituu kun | Asetukset |
|---|---|---|
| Aikataulun mukaan (`schedule`) | Cron-aikataulun mukaisesti. | `cron`, `timezone` |
| Webhook (`webhook`) | Ulkoinen järjestelmä kutsuu automaation webhook-osoitetta. | `webhook_secret` |
| AI-agentin funktio (`agent_function`) | AI-agenttisi kutsuu tätä automaatiota funktiona keskustelun aikana. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Uusi syöte-elementti (`rss`) | Uusi kohde ilmestyy RSS- tai Atom-syötteeseen. | `feed_url` |
| Sähköposti vastaanotettu (`email_received`) | Sähköposti saapuu yhdistettyyn postilaatikkoosi. | `from_contains`, `subject_contains` |
| Sovellustapahtuma (`app_event`) | Jotain tapahtuu yhdistetyssä sovelluksessa: kaupan vaihe muuttuu, maksu saapuu, lomake lähetetään. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Manuaalinen ajo (`manual`) | Vain kun se käynnistetään käsin. | ei mitään |

Automaatio voi sisältää enintään yhden käynnistimen kullekin tyypille `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` ja `contact_added`. Käynnistintä, joka aktivoituu tietuetta luotaessa, ei voi yhdistää toimintoon, joka luo saman tietueen, koska automaatio käynnistäisi itsensä.

Tietoa siitä, mitä kukin käynnistin välittää seuraaville vaiheille (`output_keys`), sekä täydellinen luettelo toiminnoista parametreineen löytyy kohdasta `GET /automations/steps`. [Automaatio-opas](../automations/automations.md#triggers) selittää jokaisen käynnistimen rakentajan näkökulmasta.

---

## Virheet

Jokaisella virheellä on tavallinen muoto `{ "success": false, "error_code": <status>, "error": "..." }`. Hylätty kaavio lisää `code`- ja `errors`-kentät: `errors` luettelee jokaisen ongelman, yhden korjattavan lauseen kerrallaan, ja `error` on ensimmäinen niistä. Korjaa täsmälleen luetellut asiat ja lähetä koko kaavio uudelleen. `code` on jokin seuraavista: `invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger` tai muu rakennustyökalun koodi.

| Tila | Milloin |
|---|---|
| `400` | Kaavio hylättiin, pakollinen kenttä puuttuu (`name` tai `graph` luonnin yhteydessä, `folder_id` siirron yhteydessä), päivitys ei sisältänyt muutoksia, tunnus ei ole kelvollinen tai kansion nimi puuttuu, on tyhjä tai liian pitkä (`code: "invalid_name"`). |
| `403` | Tilillä ei ole automaatioita; asiakastilin tilaus ei sisällä automaatioiden luomista ja muokkaamista (vain kirjoitus); tai tiimin jäsenen **Automaatiot**-käyttöoikeus on liian alhainen. |
| `404` | Tällä tilillä ei ole automaatiota kyseisellä tunnuksella, ei kansiota kyseisellä tunnuksella (`code: "folder_not_found"`) tai `sub_account_id` ei ole yksi asiakastileistäsi. |
| `409` | Samanniminen kansio on jo olemassa (`code: "folder_name_taken"`). |
| `413` | Automaatio on suurempi kuin rakennustyökalun sallima 1 Mt. Siirrä suuri koodi tai data pois sen vaiheista. |
| `422` | Rakennustyökalu hylkäsi pyynnön muusta syystä. Tarkista kaavio `GET /automations/steps`-ohjeiden mukaisesti; saman pyynnön lähettäminen uudelleen ei auta. |
| `503` | Automaatiopalveluun ei saatu yhteyttä. Yritä hetken kuluttua uudelleen. Jos olet luomassa uutta, listaa automaatiosi ensin, jotta et luo toista luonnosta. |

::: master-only
## Näiden päätepisteiden käyttäminen MCP:n kautta

Jokainen tämän sivun päätepiste on myös työkalu AI-avustajalle, jonka [yhdistät MCP:n kautta](../integrations/connect-ai-clients.md), samoilla säännöillä: uusi automaatio on luonnos, kunnes se otetaan käyttöön, ja muokkaus käynnissä olevaan automaatioon astuu voimaan välittömästi.

| Työkalu | Päätepiste |
|---|---|
| `list_automations` | `GET /automations` |
| `get_automation` | `GET /automations/{automationId}` |
| `list_automation_steps` | `GET /automations/steps` |
| `create_automation` | `POST /automations` |
| `update_automation` | `PUT /automations/{automationId}` |
| `enable_automation` | `POST /automations/{automationId}/enable` |
| `disable_automation` | `POST /automations/{automationId}/disable` |
| `list_automation_runs` | `GET /automations/{automationId}/runs` |
| `list_automation_folders` | `GET /automations/folders` |
| `create_automation_folder` | `POST /automations/folders` |
| `rename_automation_folder` | `PUT /automations/folders/{folderId}` |
| `delete_automation_folder` | `DELETE /automations/folders/{folderId}` |
| `move_automation_to_folder` | `PUT /automations/{automationId}/folder` |
:::

---

## Seuraavat vaiheet

- [Automaatiot](../automations/automations.md): miten käynnistimet, vaiheet, muuttujat ja ajohistoria toimivat rakentajassa.
- [API toimistoille](../agency/api-for-agencies.md): rakenna automaatioita asiakastilille käyttäen `sub_account_id`.
- [API-viite](reference.md): täydellinen interaktiivinen päätepisteiden selain.