# API automatyzacji

Automatyzacja to przepływ pracy składający się z kroków: jednego lub więcej wyzwalaczy, które go uruchamiają, a następnie działań, warunków, opóźnień, kroków AI i reszty, połączonych w graf. Jest to ta sama automatyzacja, którą widzisz i edytujesz na stronie [Automatyzacje](../automations/automations.md). Ten przewodnik opisuje sposób ich odczytywania i tworzenia za pomocą API.

- **Podstawowy adres URL**: `https://api.dmchamp.com/v1`
- **Uwierzytelnianie**: Twój klucz API (zobacz [Uwierzytelnianie](authentication.md))
- **Pola i treści**: każdy parametr i pole odpowiedzi znajdują się w [Dokumentacji API](reference.md#tag/automations)
- **Błędy**: zobacz [Błędy i stronicowanie](errors-and-pagination.md) oraz [Błędy](#errors) poniżej

> **Agencje:** każdy punkt końcowy na tej stronie akceptuje `sub_account_id` jako parametr zapytania, dzięki czemu możesz odczytywać i tworzyć automatyzacje klienta za pomocą klucza agencji. `sub_account_id`, który nie jest jednym z kont Twoich klientów, zwraca `404`. Zobacz [API dla agencji](../agency/api-for-agencies.md).

---

## Jak to działa: najpierw wersja robocza

API zostało zbudowane tak, aby nic nie uruchamiało się przypadkowo.

1. **Przeczytaj katalog.** `GET /automations/steps` zawiera listę wszystkich wyzwalaczy, działań i rodzajów kroków, których możesz użyć, oraz gramatykę pisania grafu (`graph_rules`).
2. **Utwórz wersję roboczą.** `POST /automations` przechowuje automatyzację **wyłączoną**. Nic jeszcze nie działa.
3. **Sprawdź ją.** Odczytaj ją, otwórz w kreatorze (odpowiedź zawiera jej `open_path`) i upewnij się, że właściciel konta widział, co ona robi i dla kogo.
4. **Włącz ją.** `POST /automations/{automationId}/enable` to osobne wywołanie. To krok, który sprawia, że dzieją się prawdziwe rzeczy: wysyłane są wiadomości, zmieniane rekordy, udostępniane narzędzia agentowi AI.

Edycja nigdy nie zmienia stanu automatyzacji (włączona/wyłączona). Oznacza to również, że edycja automatyzacji, która jest **włączona**, odnosi skutek natychmiast, w działającej automatyzacji. Aby bezpiecznie zmienić uruchomioną automatyzację, wyłącz ją, edytuj, sprawdź i włącz ponownie.

Każdy wysyłany graf przechodzi przez te same kontrole, które stosuje kanwa kreatora. Graf, którego nie można otworzyć lub uruchomić, jest odrzucany z `400`, który dokładnie wymienia, co należy naprawić.

### Dostęp

- Konto wymaga Automatyzacji. Bez tego każde wywołanie na tej stronie zwraca `403`.
- Dostęp członka zespołu zależy od jego obszaru **Automatyzacje** w [Zarządzaniu zespołem](../settings/team-management.md): odczyt (lista, pobieranie, kroki, uruchomienia, foldery) wymaga uprawnienia **Widok**, wszystko, co coś zmienia, wymaga **Edycji**.
- Na koncie klienta, którego plan nie obejmuje tworzenia i edycji automatyzacji, wywołania zapisu zwracają `403`, dokładnie tak samo, jak robi to kreator w aplikacji.

---

## Punkty końcowe

| Zadanie | Metoda + ścieżka | Eksplorator |
|---|---|---|
| Lista automatyzacji | `GET /automations` | [Otwórz w dokumentacji API](reference.md#tag/automations/GET/automations) |
| Pobierz automatyzację wraz z jej grafem | `GET /automations/{automationId}` | [Otwórz w dokumentacji API](reference.md#tag/automations/GET/automations/{automationId}) |
| Odczytaj katalog kroków | `GET /automations/steps` | [Otwórz w dokumentacji API](reference.md#tag/automations/GET/automations/steps) |
| Utwórz automatyzację (wersja robocza) | `POST /automations` | [Otwórz w dokumentacji API](reference.md#tag/automations/POST/automations) |
| Zaktualizuj automatyzację | `PUT /automations/{automationId}` | [Otwórz w dokumentacji API](reference.md#tag/automations/PUT/automations/{automationId}) |
| Włącz automatyzację | `POST /automations/{automationId}/enable` | [Otwórz w dokumentacji API](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Wyłącz automatyzację | `POST /automations/{automationId}/disable` | [Otwórz w dokumentacji API](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Odczytaj historię uruchomień | `GET /automations/{automationId}/runs` | [Otwórz w dokumentacji API](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Lista folderów | `GET /automations/folders` | [Otwórz w dokumentacji API](reference.md#tag/automations/GET/automations/folders) |
| Utwórz folder | `POST /automations/folders` | [Otwórz w dokumentacji API](reference.md#tag/automations/POST/automations/folders) |
| Zmień nazwę folderu | `PUT /automations/folders/{folderId}` | [Otwórz w dokumentacji API](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Usuń folder | `DELETE /automations/folders/{folderId}` | [Otwórz w dokumentacji API](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Przenieś automatyzację do folderu | `PUT /automations/{automationId}/folder` | [Otwórz w dokumentacji API](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Odczytywanie automatyzacji

`GET /automations` zwraca podsumowania (bez kroków), najpierw te ostatnio zmienione; `folder_id=none` wyświetla te, które nie znajdują się w żadnym folderze. `GET /automations/{automationId}` dodaje pełny `graph`: każdy krok (`nodes[]`) wraz z jego `kind`, `label`, `alias`, `action`, `params` i `config`, oraz połączenia (`edges[]`) z `from`, `to` oraz, po warunku lub podobnym elemencie, `branch`.

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

**Warto wiedzieć**

- **`alias` to sposób, w jaki późniejsze kroki odczytują wynik poprzedniego kroku**, jako `${nodes.<alias>.<field>}`. Krok bez niego jest przywoływany za pomocą swojego identyfikatora (id).
- `params` jest zachowane dla starszych czytników; `config` zawiera te same wartości i więcej (reguły warunku, prompt kroku AI, czas trwania opóźnienia, slug akcji i parametry).
- **Sekrety są ukryte.** Wartości wyglądające jak dane uwierzytelniające (sekrety webhooków, tokeny, klucze API, hasła, wartości nagłówków) są zwracane jako `"[redacted]"`. Odesłanie `"[redacted]"` bez zmian spowoduje zachowanie zapisanej wartości.
- **Długie teksty są skracane.** Pojedynczy tekst dłuższy niż około 4000 znaków jest ucinany i kończy się wielokropkiem. Jeśli odsyłasz ten krok, najpierw wstaw pełny tekst.
- Jeśli usługa automatyzacji jest nieosiągalna, otrzymasz `503`, a nie pustą listę. Pusta lista zawsze oznacza brak automatyzacji.

### Katalog kroków

`GET /automations/steps` zwraca wszystko, z czego można zbudować automatyzację: 8 `node_kinds`, każdy wyzwalacz z jego ustawieniami `fields` i `output_keys`, wbudowane `actions` z ich parametrami, `api_actions` (operacje tego API, które może wywołać krok akcji), gramatykę `graph_rules` oraz `counts`. To jest to, co **oferuje** kreator, a nie to, co zostało zbudowane na koncie: sprawdź to, zanim stwierdzisz, że wyzwalacz lub akcja nie istnieje.

- Bez `q`, kilkaset akcji API jest zwracanych jako etykiety pogrupowane według obszarów w `api_actions_by_tag`, a płaska lista jest pusta.
- Z `q` (słowo niewrażliwe na wielkość liter), `api_actions` jest płaską listą dopasowań, ograniczoną do 60 (informuje o tym `api_actions_truncated`). Akcje dla połączonych aplikacji zewnętrznych również są przeszukiwane i zwracane w `app_actions`: wyszukuj według nazwy aplikacji, na przykład `q=hubspot`. Każda z nich informuje, czy konto ma tę aplikację `connected`, a `connected_apps` wymienia te połączone. `app_actions_unavailable` to `true`, gdy akcje aplikacji nie mogły zostać przeszukane tym razem; pozostałe listy pozostają kompletne.

---

## Tworzenie i edycja

### Tworzenie wersji roboczej

```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` i `enabled: false` są normalne i nie oznaczają błędu: nowa automatyzacja jest zawsze wersją roboczą, dopóki jej nie włączysz. `warnings` wymienia to, czego kreator nie mógł ukończyć, w formie krótkich etykiet (na przykład `agent_function:not_linked`).

**Zapisywanie grafu.** `graph_rules` z katalogu to pełna gramatyka. W skrócie:

- Każdy węzeł ma `id` (unikalny w grafie), `type` (jeden z 8 [rodzajów kroków](#step-kinds)), opcjonalny `label` oraz ustawienia w `data` pod kluczem nazwanym zgodnie z jego typem (`data.trigger`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Automatyzacja wymaga co najmniej jednego wyzwalacza. Aktualna gramatyka pozwala na maksymalnie 10, a automatyzacja uruchamia się, gdy którykolwiek z nich zadziała.
- Każdy inny krok musi być osiągalny z wyzwalacza i żadne połączenie nie może prowadzić z powrotem do wcześniejszego kroku.
- Krawędzie wychodzące z warunku przenoszą `sourceHandle` `true` lub `false`; pętla `body` lub `done`; opóźnienie „Czekaj na odpowiedź” `replied` lub `timed_out`. Inne krawędzie nie mają żadnych.
- Slugi akcji i parametry pochodzą z katalogu. **Nigdy nie zgaduj identyfikatora** (agenta, tagu, listy, etapu): najpierw sprawdź go za pomocą API lub pozostaw pole jako `""`, aby użytkownik mógł wybrać je w kreatorze.
- Pozycje są opcjonalne; kroki bez nich są układane automatycznie.
- Wartości z wcześniejszych kroków są zapisywane jako `${trigger.<field>}` i `${nodes.<step>.<field>}`. Zobacz [Używanie wyników wcześniejszych kroków](../automations/automations.md#using-what-an-earlier-step-returned) oraz [Wyrażenia](../automations/automations.md#expressions).
- Graf jest akceptowany w dwóch zapisach: własnym kreatora (powyżej) oraz tym, który zwraca odczyt (`kind`, `config`, `from`, `to`, `branch`). Możesz więc odczytać automatyzację, zmienić krok i odesłać go z powrotem.
- **Tworzenie nie jest bezpieczne do powtarzania w ciemno.** Jeśli żądanie przekroczy czas oczekiwania, wyświetl listę swoich automatyzacji przed ponownym wysłaniem, w przeciwnym razie możesz skończyć z dwiema wersjami roboczymi.

### Aktualizacja

`PUT /automations/{automationId}` zmienia `name`, `description` i/lub `graph` (przynajmniej jeden lub `400`). `graph` zastępuje **cały** graf, więc zawsze pracuj na tym, co jest zapisane: odczytaj to, zmień co trzeba i odeślij cały graf z powrotem.

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

- **Zachowaj każdy `alias` kroku dokładnie w takiej formie, w jakiej go otrzymałeś.** Jeśli go zmienisz lub usuniesz, każde odwołanie do tego kroku stanie się puste. Zobacz [Nazywanie kroków](../automations/automations.md#naming-your-steps).
- **Pozostaw wartości `"[redacted]"` bez zmian** i **przywróć skrócone teksty** (tekst kończący się wielokropkiem został ucięty podczas odczytu).
- Stan włączenia automatyzacji nie jest tutaj nigdy zmieniany. Jeśli jest włączona, Twoja edycja zaczyna działać natychmiast po zapisaniu. Gdy jest włączona, zmiana, która spowodowałaby, że automatyzacja uruchomiłaby samą siebie, zostanie odrzucona: najpierw ją wyłącz.

### Włączanie i wyłączanie

`POST /automations/{automationId}/enable` włącza automatyzację, dzięki czemu od teraz uruchamia się ona zgodnie ze swoim wyzwalaczem. Wywołaj to dopiero wtedy, gdy właściciel konta zobaczy, co automatyzacja robi i dla kogo, oraz wyrazi na to zgodę. Kreator odmawia włączenia grafu, którego nie można uruchomić (brak wyzwalacza, pętla, krok wyzwalający sam siebie), zwracając `400` z wyjaśnieniem przyczyny.

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

`POST /automations/{automationId}/disable` wstrzymuje ją: trwające uruchomienia zostaną zakończone, nowe nie zostaną rozpoczęte. Wyłączanie jest zawsze dozwolone. Żadne z tych wywołań nie wymaga treści (body).

---

## Historia uruchomień

`GET /automations/{automationId}/runs` zwraca uruchomienia jednej automatyzacji, najnowsze jako pierwsze (`limit` od 1 do 50, domyślnie 10): kiedy każde z nich się rozpoczęło i zakończyło, co je wywołało, czy zakończyło się sukcesem oraz błąd w przypadku niepowodzenia. Odczytanie automatyzacji mówi Ci, co **zrobiłaby**; historia uruchomień mówi Ci, co **zrobiła** i jest to jedyny sposób, aby odróżnić automatyzację, która nigdy nie została uruchomiona, od takiej, która uruchamia się i za każdym razem kończy błędem.

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

- `mode` to `live` dla rzeczywistego uruchomienia lub `safe` dla **bezpiecznego uruchomienia** (Safe run) z edytora. Bezpieczne uruchomienie niczego nie wysyła, więc nie jest dowodem na to, że automatyzacja działa w rzeczywistym użyciu.
- Pusta lista `runs` to odpowiedź, a nie brak danych. Odpowiedź zawiera wtedy `note`: albo wyzwalacz nigdy nie został aktywowany, albo automatyzacja jest wyłączona.

---

## Foldery

Foldery służą jedynie do grupowania automatyzacji na liście. Nigdy nie zmieniają tego, co robi automatyzacja, ani tego, czy jest włączona. Zobacz [Organizowanie automatyzacji w folderach](../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" }'
```

- Wyświetlanie folderów zwraca również `unfiled_count`, czyli liczbę automatyzacji, które nie znajdują się w żadnym folderze.
- Nazwa folderu jest wymagana, może mieć do 100 znaków i musi być unikalna w ramach konta (`409`, `code: "folder_name_taken"`). Możesz również przypisać automatyzację do folderu, przekazując `folder_id` podczas jej tworzenia.
- Zmiana nazwy nie zmienia lokalizacji automatyzacji.
- **Usunięcie folderu usuwa tylko folder.** Znajdujące się w nim automatyzacje trafiają do folderu „brak” i działają dokładnie tak samo jak wcześniej; odpowiedź informuje, ile automatyzacji zostało przeniesionych (`moved_to_no_folder`).
- Przy przenoszeniu wymagane jest `folder_id`; wyślij `null`, aby usunąć automatyzację z folderu.

---

## Katalog

### Rodzaje kroków

| Rodzaj | Co robi |
|---|---|
| `trigger` | Uruchamia automatyzację, gdy coś się wydarzy. |
| `action` | Wykonuje jeden krok: wbudowaną akcję, akcję API, akcję połączonej aplikacji, żądanie HTTP lub wiadomość e-mail. |
| `condition` | Dzieli przepływ na podstawie reguły na gałąź `true` i `false`. |
| `transform` | Uruchamia krótki fragment kodu w celu przekształcenia danych między krokami. |
| `ai` | Zadaje pytanie AI za pomocą napisanego przez Ciebie promptu. Może zwrócić tekst, oddzielne pola lub wybrać jedną z kilku gałęzi. |
| `delay` | Czeka określony czas lub czeka na odpowiedź kontaktu (z limitem czasu). |
| `loop` | Powtarza kroki wewnątrz dla każdego elementu na liście. |
| `respond` | Zwraca odpowiedź na wywołanie webhooka lub wywołanie funkcji agenta AI, które rozpoczęło uruchomienie. |

### Wyzwalacze

Oto 40 wyzwalaczy wymienionych obecnie w katalogu, pogrupowanych tak, jak w kreatorze. Kolumna **Ustawienia** zawiera klucze ustawień wyzwalacza (`fields`), które zawężają moment jego aktywacji. Każdy wyzwalacz przyjmuje również `respect_quiet_hours`, `run_hours`, `reentry` oraz `stop_on_response`; zobacz [Ustawienia automatyzacji](../automations/automations.md#automation-settings).

**Wiadomości**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Wiadomość przychodząca (`incoming_message`) | Kontakt wysyła wiadomość na dowolnym kanale. | `campaign` (ogranicza do jednego agenta AI), `channel`, `message_filter_contains` (słowo kluczowe), `message_filter_regex` (wzorzec) |
| Nieodebrane połączenie (`missed_call`) | Ktoś dzwoni na jeden z Twoich numerów WhatsApp Web lub Twój własny numer SMS i nikt nie odbiera. | `to_number` |
| Wiadomość dostarczona (`message_delivered`) | Wysłana przez Ciebie wiadomość została potwierdzona jako dostarczona przez kanał. | `channel`, `agent` |
| Wiadomość nieudana (`message_failed`) | Wysłana przez Ciebie wiadomość nie mogła zostać dostarczona (zawiera błąd). | `channel`, `agent` |
| Wiadomość wysłana (`message_sent`) | Dowolna wiadomość opuszcza Twoje konto: agenta AI, Twoją, transmisję lub wiadomość uzupełniającą. Przefiltruj ją, w przeciwnym razie uruchomi się dla wszystkich. | `channel`, `sent_by` |
| Wiadomość uzupełniająca wysłana (`follow_up_sent`) | Automatyczna wiadomość uzupełniająca zostaje wysłana. | brak |
| Wiadomość uzupełniająca pominięta (`follow_up_skipped`) | Wiadomość uzupełniająca została wstrzymana, ponieważ warunek wysyłki nie został spełniony. | brak |
| Wiadomości uzupełniające zakończone (`follow_up_exhausted`) | Kontakt otrzymał ostatnią wiadomość uzupełniającą w sekwencji i nic więcej nie jest w kolejce. | brak |
| Konwersacja zamknięta (`conversation_closed`) | Czat zostaje zamknięty, z informacją o sposobie zakończenia i podsumowaniem. | `channel`, `agent` |
| Transmisja zakończona (`broadcast_completed`) | Transmisja zakończyła wysyłanie, z informacją o liczbie wysłanych i nieudanych wiadomości. | brak |
| Odpowiedź leada posortowana (`outreach_reply_labelled`) | Odpowiedź leada z zimnej kampanii e-mailowej zostaje posortowana, na przykład jako Zainteresowany. | `label` |
| Komentarz Skool otrzymany (`skool_comment_received`) | Członek komentuje post w Skool, który obserwuje jedna z Twoich reguł komentarzy. | brak |

**Kontakty**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Nowy kontakt (`contact_created`) | Nowa osoba kontaktuje się z Tobą po raz pierwszy na dowolnym kanale, a także w przypadku importów, API i kontaktów dodanych ręcznie. | brak |
| Kontakt zaktualizowany (`contact_updated`) | Pole kontaktu ulega zmianie. | `field` |
| Kontakty dodane tutaj (`contact_added`) | Tylko dla kontaktów, które samodzielnie dodasz do tej automatyzacji ze strony Kontakty. Jedno uruchomienie na kontakt. | brak |
| Etykieta zastosowana (`tag_applied`) | Etykieta zostaje dodana do kontaktu przez Twojego agenta AI, osobę, automatyzację lub import. | `tag_name`, `channel`, `applied_by` |
| Etykieta usunięta (`tag_removed`) | Etykieta zostaje usunięta z kontaktu. | `tag_name`, `channel` |
| Członek Skool dołączył (`skool_member_joined`) | Ktoś dołącza do społeczności Skool, którą posiadasz lub prowadzisz, wraz z profilem, odpowiedziami i wynikiem dopasowania. | `group_id`, `create_contact` |
| Członek Skool zakwalifikowany (`skool_member_qualified`) | Odpowiedzi nowego członka Skool osiągają wynik równy lub wyższy od Twojego progu. | `min_score` |

**Transakcje**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Transakcja utworzona (`deal_created`) | Nowa transakcja zostaje dodana do jednego z Twoich lejów sprzedaży. | `pipeline_id`, `stage_id` |
| Etap transakcji zmieniony (`deal_stage_changed`) | Transakcja przenosi się do innego etapu, wskazując etap, który opuściła i do którego weszła. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Transakcja zaktualizowana (`deal_updated`) | Pole transakcji ulega zmianie. | `field` |

**Spotkania**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Spotkanie zarezerwowane (`appointment_booked`) | Nowe spotkanie zostaje zarezerwowane. | brak |
| Spotkanie anulowane (`appointment_cancelled`) | Zarezerwowane spotkanie zostaje anulowane. | brak |
| Spotkanie przełożone (`appointment_rescheduled`) | Zarezerwowane spotkanie zostaje przeniesione na inny termin, z podaniem starego i nowego czasu. | `event_id` |
| Przed spotkaniem (`appointment_upcoming`) | Określony czas przed każdym potwierdzonym spotkaniem, w celu wysłania przypomnień. Do pięciu przypomnień na automatyzację. | `offsets_minutes` |

**Zadania**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Zadanie utworzone (`task_created`) | Zadanie zostaje utworzone. | `task_type` |
| Zadanie ukończone (`task_completed`) | Zadanie zostaje przeniesione do etapu ukończonego. | brak |

**Konto**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Niski stan środków (`low_credit_balance`) | Twój stan środków spada poniżej progu alertu. | brak |
| Kanał połączony (`channel_connected`) | Jeden z Twoich kanałów kończy łączenie. | `channel` |
| Kanał rozłączony (`channel_disconnected`) | Jeden z Twoich kanałów zostaje rozłączony: wylogowany, odłączony lub przerwany. Numer WhatsApp Web, który łączy się automatycznie, liczy się tylko wtedy, gdy pozostaje nieaktywny przez ponad 30 minut. | `channel` |

**Agencja**

| Wyzwalacz (`kind`) | Aktywuje się, gdy | Ustawienia |
|---|---|---|
| Podkonto utworzone (`sub_account_created`) | Nowe konto klienta zostaje utworzone z poziomu Twojego pulpitu nawigacyjnego, API lub strony rejestracji. | brak |
| Aktywność podkonta (`sub_account_event`) | Coś dzieje się na jednym z Twoich kont klientów: kończą się środki, łączy się kanał, następuje zmiana planu. | `event`, `threshold` |

**Ogólne i aplikacje**

| Wyzwalacz (`kind`) | Uruchamia się, gdy | Ustawienia |
|---|---|---|
| Według harmonogramu (`schedule`) | Zgodnie z harmonogramem cron. | `cron`, `timezone` |
| Webhook (`webhook`) | Zewnętrzny system wywołuje adres webhook automatyzacji. | `webhook_secret` |
| Funkcja agenta AI (`agent_function`) | Twój agent AI wywołuje tę automatyzację jako funkcję podczas rozmowy. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Nowy element kanału (`rss`) | Nowy element pojawia się w kanale RSS lub Atom. | `feed_url` |
| Otrzymano e-mail (`email_received`) | E-mail dociera do Twojej połączonej skrzynki odbiorczej. | `from_contains`, `subject_contains` |
| Zdarzenie w aplikacji (`app_event`) | Coś dzieje się w połączonej aplikacji: zmienia się etap transakcji, wpływa płatność, formularz zostaje przesłany. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Ręczne uruchomienie (`manual`) | Tylko po ręcznym uruchomieniu. | brak |

Automatyzacja może zawierać maksymalnie jeden wyzwalacz każdego typu: `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` oraz `contact_added`. Wyzwalacz, który uruchamia się po utworzeniu rekordu, nie może być połączony z akcją tworzącą ten sam rekord, ponieważ automatyzacja uruchamiałaby samą siebie.

Aby dowiedzieć się, co każdy wyzwalacz przekazuje do kolejnych kroków (`output_keys`) oraz poznać pełną listę akcji wraz z ich parametrami, przeczytaj `GET /automations/steps`. [Przewodnik po automatyzacjach](../automations/automations.md#triggers) wyjaśnia każdy wyzwalacz językiem używanym w kreatorze.

---

## Błędy

Każdy błąd ma standardowy format `{ "success": false, "error_code": <status>, "error": "..." }`. Odrzucony graf dodaje `code` oraz `errors`: `errors` wymienia każdy problem, po jednym zdaniu na każdy możliwy do naprawienia błąd, a `error` to pierwszy z nich. Napraw dokładnie to, co zostało wymienione, i wyślij cały graf ponownie. `code` to jeden z kodów `invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger` lub inny kod pochodzący z kreatora.

| Status | Kiedy |
|---|---|
| `400` | Graf został odrzucony, brakuje wymaganego pola (`name` lub `graph` przy tworzeniu, `folder_id` przy przenoszeniu), aktualizacja niczego nie zmieniła, identyfikator jest nieprawidłowy lub nazwa folderu jest brakująca, pusta lub zbyt długa (`code: "invalid_name"`). |
| `403` | Konto nie posiada automatyzacji; plan konta klienta nie obejmuje tworzenia i edycji automatyzacji (tylko zapis); lub uprawnienia członka zespołu do **Automatyzacji** są zbyt niskie. |
| `404` | Brak automatyzacji o tym identyfikatorze na tym koncie, brak folderu o tym identyfikatorze (`code: "folder_not_found"`) lub `sub_account_id`, który nie jest jednym z Twoich kont klientów. |
| `409` | Folder o tej nazwie już istnieje (`code: "folder_name_taken"`). |
| `413` | Automatyzacja jest większa niż 1 MB akceptowany przez kreator. Przenieś duży kod lub dane poza jej kroki. |
| `422` | Kreator odrzucił żądanie z innego powodu. Sprawdź graf pod kątem `GET /automations/steps`; ponowne wysłanie tego samego żądania nie pomoże. |
| `503` | Nie można było połączyć się z usługą automatyzacji. Spróbuj ponownie za chwilę. W przypadku tworzenia, najpierw wyświetl listę swoich automatyzacji, aby nie utworzyć drugiego szkicu. |

::: master-only
## Używanie tych punktów końcowych przez MCP

Każdy punkt końcowy na tej stronie jest również narzędziem dla asystenta AI, którego [podłączasz przez MCP](../integrations/connect-ai-clients.md), przy zachowaniu tych samych zasad: nowa automatyzacja jest szkicem, dopóki nie zostanie włączona, a edycja działającej automatyzacji wchodzi w życie natychmiast.

| Narzędzie | Punkt końcowy |
|---|---|
| `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` |
:::

---

## Następne kroki

- [Automatyzacje](../automations/automations.md): jak działają wyzwalacze, kroki, zmienne i historia uruchomień w kreatorze.
- [API dla agencji](../agency/api-for-agencies.md): buduj automatyzacje na koncie klienta za pomocą `sub_account_id`.
- [Dokumentacja API](reference.md): pełny interaktywny eksplorator punktów końcowych.