# Automations-API

Eine Automatisierung ist ein Workflow, der aus Schritten besteht: einem oder mehreren Triggern, die ihn starten, gefolgt von Aktionen, Bedingungen, Verzögerungen, KI-Schritten und dem Rest, die zu einem Graphen verbunden sind. Es ist dieselbe Automatisierung, die Sie auf der Seite [Automatisierungen](../automations/automations.md) sehen und bearbeiten können. Dieser Leitfaden behandelt das Lesen und Erstellen dieser Automatisierungen über die API.

- **Basis-URL**: `https://api.dmchamp.com/v1`
- **Authentifizierung**: Ihr API-Schlüssel (siehe [Authentifizierung](authentication.md))
- **Felder und Bodies**: Jeder Parameter und jedes Antwortfeld befindet sich in der [API-Referenz](reference.md#tag/automations)
- **Fehler**: Siehe [Fehler & Paginierung](errors-and-pagination.md) und [Fehler](#errors) unten

> **Agenturen:** Jeder Endpunkt auf dieser Seite akzeptiert `sub_account_id` als Abfrageparameter, sodass Sie die Automatisierungen eines Kunden mit Ihrem Agenturschlüssel lesen und erstellen können. Ein `sub_account_id`, das kein Kundenkonto von Ihnen ist, gibt `404` zurück. Siehe [API für Agenturen](../agency/api-for-agencies.md).

---

## Funktionsweise: Zuerst ein Entwurf

Die API ist so aufgebaut, dass nichts versehentlich gestartet wird.

1. **Katalog lesen.** `GET /automations/steps` listet jeden Trigger, jede Aktion und jeden Schritttyp auf, den Sie verwenden können, sowie die Grammatik zum Schreiben eines Graphen (`graph_rules`).
2. **Entwurf erstellen.** `POST /automations` speichert die Automatisierung im Status **ausgeschaltet**. Es läuft noch nichts.
3. **Überprüfen.** Lesen Sie sie zurück, öffnen Sie sie im Builder (die Antwort liefert Ihnen die `open_path`) und stellen Sie sicher, dass der Kontoinhaber gesehen hat, was sie tut und für wen.
4. **Einschalten.** `POST /automations/{automationId}/enable` ist ein eigener Aufruf. Dies ist der Schritt, der echte Aktionen auslöst: Nachrichten werden gesendet, Datensätze geändert, Werkzeuge an einen KI-Agenten übergeben.

Das Bearbeiten ändert niemals, ob eine Automatisierung ein- oder ausgeschaltet ist. Das bedeutet auch, dass eine Änderung an einer **eingeschalteten** Automatisierung sofort wirksam wird, direkt in der laufenden Automatisierung. Um eine laufende Automatisierung sicher zu ändern, deaktivieren Sie sie, bearbeiten Sie sie, überprüfen Sie sie und aktivieren Sie sie erneut.

Jeder Graph, den Sie senden, durchläuft dieselben Prüfungen, die auch der Builder-Canvas anwendet. Ein Graph, der nicht geöffnet oder ausgeführt werden kann, wird mit einem `400` abgelehnt, das genau auflistet, was zu korrigieren ist.

### Zugriff

- Das Konto benötigt Automatisierungen. Ohne diese Berechtigung gibt jeder Aufruf auf dieser Seite `403` zurück.
- Der Zugriff eines Teammitglieds richtet sich nach seinem Bereich **Automatisierungen** in der [Teamverwaltung](../settings/team-management.md): Lesen (Liste, Abrufen, Schritte, Ausführungen, Ordner) erfordert **Anzeigen**, alles, was etwas ändert, erfordert **Bearbeiten**.
- Bei einem Kundenkonto, dessen Plan das Erstellen und Bearbeiten von Automatisierungen nicht vorsieht, geben die Schreibaufrufe `403` zurück, genau wie der Builder in der App.

---

## Endpunkte

| Aufgabe | Methode + Pfad | Explorer |
|---|---|---|
| Automatisierungen auflisten | `GET /automations` | [In API-Referenz öffnen](reference.md#tag/automations/GET/automations) |
| Eine Automatisierung mit ihrem Graphen abrufen | `GET /automations/{automationId}` | [In API-Referenz öffnen](reference.md#tag/automations/GET/automations/{automationId}) |
| Den Schrittkatalog lesen | `GET /automations/steps` | [In API-Referenz öffnen](reference.md#tag/automations/GET/automations/steps) |
| Eine Automatisierung erstellen (Entwurf) | `POST /automations` | [In API-Referenz öffnen](reference.md#tag/automations/POST/automations) |
| Eine Automatisierung aktualisieren | `PUT /automations/{automationId}` | [In API-Referenz öffnen](reference.md#tag/automations/PUT/automations/{automationId}) |
| Einschalten | `POST /automations/{automationId}/enable` | [In API-Referenz öffnen](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Ausschalten | `POST /automations/{automationId}/disable` | [In API-Referenz öffnen](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Ausführungshistorie lesen | `GET /automations/{automationId}/runs` | [In API-Referenz öffnen](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Ordner auflisten | `GET /automations/folders` | [In API-Referenz öffnen](reference.md#tag/automations/GET/automations/folders) |
| Einen Ordner erstellen | `POST /automations/folders` | [In API-Referenz öffnen](reference.md#tag/automations/POST/automations/folders) |
| Einen Ordner umbenennen | `PUT /automations/folders/{folderId}` | [In API-Referenz öffnen](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Einen Ordner löschen | `DELETE /automations/folders/{folderId}` | [In API-Referenz öffnen](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Eine Automatisierung in einen Ordner verschieben | `PUT /automations/{automationId}/folder` | [In API-Referenz öffnen](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Automatisierungen lesen

`GET /automations` gibt Zusammenfassungen zurück (ohne Schritte), sortiert nach der letzten Änderung; `folder_id=none` listet diejenigen auf, die sich in keinem Ordner befinden. `GET /automations/{automationId}` fügt den vollständigen `graph` hinzu: jeden Schritt (`nodes[]`) mit seinem `kind`, `label`, `alias`, `action`, `params` und `config` sowie die Verbindungen (`edges[]`) mit `from`, `to` und, nach einer Bedingung oder Ähnlichem, `branch`.

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

**Gut zu wissen**

- **`alias` ist die Art und Weise, wie spätere Schritte die Ausgabe eines Schritts lesen**, als `${nodes.<alias>.<field>}`. Ein Schritt ohne einen solchen wird über seine ID referenziert.
- `params` wird für ältere Reader beibehalten; `config` enthält dieselben Werte und mehr (die Regeln einer Bedingung, den Prompt eines KI-Schritts, die Dauer einer Verzögerung, den Slug und die Parameter einer Aktion).
- **Geheimnisse sind verborgen.** Werte, die wie Anmeldedaten aussehen (Webhook-Geheimnisse, Token, API-Schlüssel, Passwörter, Header-Werte), werden als `"[redacted]"` zurückgegeben. Senden Sie `"[redacted]"` unverändert zurück, damit der gespeicherte Wert erhalten bleibt.
- **Lange Texte werden gekürzt.** Ein einzelner Text, der länger als etwa 4.000 Zeichen ist, wird abgeschnitten und endet mit Auslassungspunkten. Wenn Sie diesen Schritt zurücksenden, fügen Sie zuerst den vollständigen Text wieder ein.
- Wenn der Automatisierungsdienst nicht erreicht werden kann, erhalten Sie einen `503`, niemals eine leere Liste an seiner Stelle. Eine leere Liste bedeutet immer, dass keine Automatisierungen vorhanden sind.

### Der Schrittkatalog

`GET /automations/steps` gibt alles zurück, woraus eine Automatisierung erstellt werden kann: die 8 `node_kinds`, jeden Trigger mit seinen Einstellungen `fields` und `output_keys`, die integrierten `actions` mit ihren Parametern, die `api_actions` (Operationen dieser API, die ein Aktionsschritt aufrufen kann), die `graph_rules`-Grammatik und `counts`. Dies ist das, was der Builder **anbietet**, nicht das, was das Konto erstellt hat: Überprüfen Sie dies, bevor Sie schlussfolgern, dass ein Trigger oder eine Aktion nicht existiert.

- Ohne `q` werden die mehreren hundert API-Aktionen als nach Bereichen gruppierte Labels in `api_actions_by_tag` zurückgegeben und die flache Liste ist leer.
- Mit `q` (einem Wort ohne Berücksichtigung der Groß-/Kleinschreibung) ist `api_actions` die flache Liste der Übereinstimmungen, begrenzt auf 60 (`api_actions_truncated` gibt an, wann). Aktionen für verbundene Drittanbieter-Apps werden ebenfalls durchsucht und in `app_actions` zurückgegeben: Suchen Sie nach dem Namen der App, zum Beispiel `q=hubspot`. Jede gibt an, ob das Konto über diese App `connected` verfügt, und `connected_apps` listet die verbundenen auf. `app_actions_unavailable` ist `true`, wenn die App-Aktionen diesmal nicht durchsucht werden konnten; die anderen Listen sind weiterhin vollständig.

---

## Erstellen und Bearbeiten

### Einen Entwurf erstellen

```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` und `enabled: false` sind normal, kein Fehler: Eine neue Automatisierung ist immer ein Entwurf, bis Sie sie aktivieren. `warnings` listet auf, was der Builder nicht fertigstellen konnte, als kurze Labels (zum Beispiel `agent_function:not_linked`).

**Den Graphen schreiben.** `graph_rules` aus dem Katalog ist die vollständige Grammatik. Kurz gesagt:

- Jeder Knoten hat eine `id` (eindeutig im Graphen), eine `type` (eine der 8 [Schrittarten](#step-kinds)), optional eine `label` und seine Einstellungen in `data` unter einem Schlüssel, der nach seinem Typ benannt ist (`data.trigger`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Eine Automatisierung benötigt mindestens einen Trigger. Die Live-Grammatik erlaubt bis zu 10, und die Automatisierung startet, wenn einer von ihnen ausgelöst wird.
- Jeder andere Schritt muss von einem Trigger aus erreichbar sein, und keine Verbindung darf zu einem früheren Schritt zurückführen.
- Kanten, die eine Bedingung verlassen, tragen `sourceHandle` `true` oder `false`; eine Schleife `body` oder `done`; eine „Auf Antwort warten“-Verzögerung `replied` oder `timed_out`. Andere Kanten haben keine.
- Aktions-Slugs und -Parameter stammen aus dem Katalog. **Raten Sie niemals eine ID** (einen Agenten, ein Tag, eine Liste, eine Phase): Schlagen Sie sie zuerst über die API nach oder lassen Sie das Feld als `""`, damit die Person es im Builder auswählen kann.
- Positionen sind optional; Schritte ohne Position werden automatisch angeordnet.
- Werte aus früheren Schritten werden als `${trigger.<field>}` und `${nodes.<step>.<field>}` geschrieben. Siehe [Verwendung der Rückgabe eines früheren Schritts](../automations/automations.md#using-what-an-earlier-step-returned) und [Ausdrücke](../automations/automations.md#expressions).
- Der Graph wird in zwei Schreibweisen akzeptiert: der eigenen des Builders (oben) und derjenigen, mit der eine Leseanfrage antwortet (`kind`, `config`, `from`, `to`, `branch`). Sie können also eine Automatisierung lesen, einen Schritt ändern und sie zurücksenden.
- **Ein Erstellen-Vorgang ist nicht sicher blind zu wiederholen.** Wenn eine Anfrage ein Zeitlimit überschreitet, listen Sie Ihre Automatisierungen auf, bevor Sie sie erneut senden, sonst könnten Sie am Ende zwei Entwürfe haben.

### Aktualisieren

`PUT /automations/{automationId}` ändert `name`, `description` und/oder `graph` (mindestens eines oder `400`). Ein `graph` ersetzt den **gesamten** Graphen. Arbeiten Sie daher immer mit dem, was gespeichert ist: Lesen Sie es, ändern Sie, was Sie benötigen, und senden Sie den gesamten Graphen zurück.

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

- **Behalten Sie bei jedem Schritt die `alias` exakt so bei, wie Sie sie erhalten haben.** Wenn Sie diese ändern oder löschen, läuft jeder Verweis auf diesen Schritt ins Leere. Siehe [Benennung Ihrer Schritte](../automations/automations.md#naming-your-steps).
- **Belassen Sie `"[redacted]"`-Werte unverändert** und **stellen Sie gekürzte Texte wieder her** (ein Text, der mit Auslassungspunkten endet, wurde beim Lesen abgeschnitten).
- Ob die Automatisierung aktiviert ist, wird hier nie geändert. Wenn sie aktiviert ist, wird Ihre Änderung sofort nach dem Speichern wirksam. Während sie aktiviert ist, wird eine Änderung, die dazu führen würde, dass sie sich selbst auslöst, abgelehnt: Deaktivieren Sie sie zuerst.

### Aktivieren und Deaktivieren

`POST /automations/{automationId}/enable` schaltet eine Automatisierung ein, sodass sie ab sofort bei ihrem Auslöser ausgeführt wird. Rufen Sie dies erst auf, wenn der Kontoinhaber gesehen hat, was die Automatisierung tut und bei wem, und zugestimmt hat. Der Builder verweigert das Einschalten eines Graphen, der nicht ausgeführt werden kann (kein Auslöser, eine Schleife, ein Schritt, der sich selbst auslöst), mit einem `400`, das den Grund nennt.

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

`POST /automations/{automationId}/disable` pausiert sie: Bereits laufende Ausführungen werden beendet, keine neuen werden gestartet. Das Deaktivieren ist immer zulässig. Keiner der Aufrufe benötigt einen Body.

---

## Ausführungsverlauf

`GET /automations/{automationId}/runs` gibt die Ausführungen einer Automatisierung zurück, beginnend mit der neuesten (`limit` 1 bis 50, Standard 10): wann jede gestartet und beendet wurde, was sie ausgelöst hat, ob sie erfolgreich war und den Fehler bei einem Fehlschlag. Das Lesen der Automatisierung verrät Ihnen, was sie **tun würde**; der Ausführungsverlauf verrät Ihnen, was sie **getan hat**. Dies ist die einzige Möglichkeit, eine Automatisierung, die nie ausgeführt wurde, von einer zu unterscheiden, die ausgeführt wird und jedes Mal fehlschlägt.

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

- `mode` ist `live` für eine echte Ausführung oder `safe` für eine **Sichere Ausführung** aus dem Editor. Eine sichere Ausführung sendet nichts, ist also kein Beweis dafür, dass die Automatisierung im realen Einsatz funktioniert.
- Eine leere `runs`-Liste ist eine Antwort, keine Lücke. Die Antwort enthält dann ein `note`: Entweder wurde der Auslöser nie ausgelöst oder die Automatisierung ist ausgeschaltet.

---

## Ordner

Ordner gruppieren Automatisierungen in der Liste lediglich. Sie ändern niemals, was eine Automatisierung tut oder ob sie eingeschaltet ist. Siehe [Automatisierungen in Ordnern organisieren](../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" }'
```

- Das Auflisten von Ordnern gibt auch `unfiled_count` zurück, wie viele Automatisierungen sich in keinem Ordner befinden.
- Ein Ordnername ist erforderlich, darf bis zu 100 Zeichen lang sein und muss im Konto eindeutig sein (`409`, `code: "folder_name_taken"`). Sie können eine Automatisierung auch ablegen, indem Sie beim Erstellen `folder_id` übergeben.
- Das Umbenennen belässt die Automatisierungen dort, wo sie sind.
- **Das Löschen eines Ordners löscht nur den Ordner.** Seine Automatisierungen werden in keinen Ordner verschoben und laufen genau wie zuvor weiter; die Antwort gibt an, wie viele verschoben wurden (`moved_to_no_folder`).
- Beim Verschieben ist `folder_id` erforderlich; senden Sie `null`, um die Automatisierung aus ihrem Ordner zu entfernen.

---

## Katalog

### Schrittarten

| Art | Was sie bewirkt |
|---|---|
| `trigger` | Startet die Automatisierung, wenn etwas passiert. |
| `action` | Führt einen Schritt aus: eine integrierte Aktion, eine API-Aktion, eine Aktion einer verbundenen App, eine HTTP-Anfrage oder eine E-Mail. |
| `condition` | Teilt den Ablauf basierend auf einer Regel in einen `true`- und einen `false`-Zweig auf. |
| `transform` | Führt ein kurzes Stück Code aus, um Daten zwischen Schritten umzuwandeln. |
| `ai` | Befragt die KI mit einem von Ihnen geschriebenen Prompt. Sie kann Text zurückgeben, Felder trennen oder einen von mehreren Zweigen auswählen. |
| `delay` | Wartet eine festgelegte Zeit lang oder wartet auf eine Antwort des Kontakts (mit Zeitüberschreitung). |
| `loop` | Wiederholt die darin enthaltenen Schritte für jedes Element in einer Liste. |
| `respond` | Gibt eine Antwort an den Webhook-Aufruf oder den KI-Agenten-Funktionsaufruf zurück, der den Durchlauf gestartet hat. |

### Auslöser (Trigger)

Dies sind die 40 Trigger, die der Katalog heute auflistet, gruppiert so, wie der Builder sie gruppiert. Die Spalte **Einstellungen** enthält die eigenen Einstellungsschlüssel des Triggers (`fields`), die einschränken, wann er ausgelöst wird. Jeder Trigger akzeptiert außerdem `respect_quiet_hours`, `run_hours`, `reentry` und `stop_on_response`; siehe [Automatisierungseinstellungen](../automations/automations.md#automation-settings).

**Messaging**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Eingehende Nachricht (`incoming_message`) | Ein Kontakt sendet eine Nachricht über einen beliebigen Kanal. | `campaign` (beschränkt auf einen KI-Agenten), `channel`, `message_filter_contains` (Stichwort), `message_filter_regex` (Muster) |
| Verpasster Anruf (`missed_call`) | Jemand ruft eine Ihrer WhatsApp Web-Nummern oder Ihre eigene SMS-Nummer an und niemand nimmt ab. | `to_number` |
| Nachricht zugestellt (`message_delivered`) | Eine von Ihnen gesendete Nachricht wird vom Kanal als zugestellt bestätigt. | `channel`, `agent` |
| Nachricht fehlgeschlagen (`message_failed`) | Eine von Ihnen gesendete Nachricht konnte nicht zugestellt werden, inklusive Fehler. | `channel`, `agent` |
| Nachricht gesendet (`message_sent`) | Jede Nachricht, die Ihr Konto verlässt: die des KI-Agenten, Ihre eigene, eine Broadcast-Nachricht, eine Nachfassaktion. Filtern Sie diese, sonst wird sie für alle ausgeführt. | `channel`, `sent_by` |
| Nachfassaktion gesendet (`follow_up_sent`) | Eine automatische Nachfassaktion wird versendet. | keine |
| Nachfassaktion übersprungen (`follow_up_skipped`) | Eine Nachfassaktion wurde zurückgehalten, weil ihre Sende-Bedingung nicht erfüllt war. | keine |
| Nachfassaktionen beendet (`follow_up_exhausted`) | Ein Kontakt hat die letzte Nachfassaktion in der Sequenz erhalten und es steht nichts mehr in der Warteschlange. | keine |
| Konversation geschlossen (`conversation_closed`) | Ein Chat wird geschlossen, inklusive Art des Abschlusses und einer Zusammenfassung. | `channel`, `agent` |
| Broadcast beendet (`broadcast_completed`) | Ein Broadcast wurde fertig versendet, inklusive Anzahl der versendeten und fehlgeschlagenen Nachrichten. | keine |
| Lead-Antwort sortiert (`outreach_reply_labelled`) | Die Antwort eines Cold-Email-Leads wird sortiert, zum Beispiel als Interessiert. | `label` |
| Skool-Kommentar erhalten (`skool_comment_received`) | Ein Mitglied kommentiert unter einem Skool-Beitrag, den eine Ihrer Kommentarregeln überwacht. | keine |

**Kontakte**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Neuer Kontakt (`contact_created`) | Eine neue Person erreicht Sie zum ersten Mal über einen beliebigen Kanal, sowie bei Importen, über die API und bei Kontakten, die Sie manuell erstellen. | keine |
| Kontakt aktualisiert (`contact_updated`) | Ein Kontaktfeld ändert sich. | `field` |
| Kontakte, die Sie hier hinzufügen (`contact_added`) | Nur für Kontakte, die Sie selbst über die Kontaktseite in diese Automatisierung einfügen. Ein Durchlauf pro Kontakt. | keine |
| Tag hinzugefügt (`tag_applied`) | Ein Tag wird einem Kontakt hinzugefügt, durch Ihren KI-Agenten, eine Person, eine Automatisierung oder einen Import. | `tag_name`, `channel`, `applied_by` |
| Tag entfernt (`tag_removed`) | Ein Tag wird von einem Kontakt entfernt. | `tag_name`, `channel` |
| Skool-Mitglied beigetreten (`skool_member_joined`) | Jemand tritt einer Skool-Community bei, die Sie besitzen oder leiten, inklusive Profil, Antworten und Eignungs-Score. | `group_id`, `create_contact` |
| Skool-Mitglied qualifiziert (`skool_member_qualified`) | Die Antworten eines neuen Skool-Mitglieds erreichen oder übertreffen Ihren Schwellenwert. | `min_score` |

**Deals**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Deal erstellt (`deal_created`) | Ein neuer Deal wird einer Ihrer Pipelines hinzugefügt. | `pipeline_id`, `stage_id` |
| Deal-Phase geändert (`deal_stage_changed`) | Ein Deal wechselt in eine andere Phase, unter Angabe der Phase, die er verlassen hat, und derjenigen, in die er eingetreten ist. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Deal aktualisiert (`deal_updated`) | Ein Deal-Feld ändert sich. | `field` |

**Termine**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Termin gebucht (`appointment_booked`) | Ein neuer Termin wird gebucht. | keine |
| Termin storniert (`appointment_cancelled`) | Ein gebuchter Termin wird storniert. | keine |
| Termin verschoben (`appointment_rescheduled`) | Ein gebuchter Termin wird auf eine andere Zeit verschoben, wobei die alte Zeit neben der neuen angezeigt wird. | `event_id` |
| Vor einem Termin (`appointment_upcoming`) | Eine festgelegte Zeit vor jedem bestätigten Termin, für Erinnerungen. Bis zu fünf Erinnerungen pro Automatisierung. | `offsets_minutes` |

**Aufgaben**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Aufgabe erstellt (`task_created`) | Eine Aufgabe wird erstellt. | `task_type` |
| Aufgabe abgeschlossen (`task_completed`) | Eine Aufgabe wird in eine abgeschlossene Phase verschoben. | keine |

**Konto**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Niedriger Guthabenstand (`low_credit_balance`) | Ihr Guthaben fällt unter Ihren Warnschwellenwert. | keine |
| Kanal verbunden (`channel_connected`) | Einer Ihrer Kanäle hat die Verbindung hergestellt. | `channel` |
| Kanal getrennt (`channel_disconnected`) | Einer Ihrer Kanäle ist ausgefallen: abgemeldet, entkoppelt oder unterbrochen. Eine WhatsApp Web-Nummer, die sich von selbst wieder verbindet, zählt nur, wenn sie nach 30 Minuten immer noch offline ist. | `channel` |

**Agentur**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Unterkonto erstellt (`sub_account_created`) | Ein neues Kundenkonto wird erstellt, über Ihr Dashboard, die API oder Ihre Anmeldeseite. | keine |
| Unterkonto-Aktivität (`sub_account_event`) | Etwas passiert in einem Ihrer Kundenkonten: Guthaben wird knapp, ein Kanal verbindet sich, ein Planwechsel. | `event`, `threshold` |

**Allgemein und Apps**

| Trigger (`kind`) | Löst aus bei | Einstellungen |
|---|---|---|
| Nach Zeitplan (`schedule`) | Nach einem Cron-Zeitplan. | `cron`, `timezone` |
| Webhook (`webhook`) | Ein externes System ruft die Webhook-Adresse der Automatisierung auf. | `webhook_secret` |
| KI-Agent-Funktion (`agent_function`) | Ihr KI-Agent ruft diese Automatisierung während eines Gesprächs als Funktion auf. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Neues Feed-Element (`rss`) | Ein neues Element erscheint in einem RSS- oder Atom-Feed. | `feed_url` |
| E-Mail empfangen (`email_received`) | Eine E-Mail geht in Ihrem verbundenen Postfach ein. | `from_contains`, `subject_contains` |
| App-Ereignis (`app_event`) | Etwas passiert in einer verbundenen App: eine Deal-Phase ändert sich, eine Zahlung geht ein, ein Formular wird abgesendet. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Manuelle Ausführung (`manual`) | Nur wenn sie manuell gestartet wird. | keine |

Eine Automatisierung kann jeweils höchstens einen Trigger der Typen `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` und `contact_added` enthalten. Ein Trigger, der bei der Erstellung eines Datensatzes ausgelöst wird, kann nicht mit der Aktion kombiniert werden, die denselben Datensatz erstellt, da sich die Automatisierung sonst selbst auslösen würde.

Informationen darüber, was jeder Trigger an nachfolgende Schritte (`output_keys`) weitergibt, sowie die vollständige Liste der Aktionen mit ihren Parametern finden Sie unter `GET /automations/steps`. Der [Automatisierungsleitfaden](../automations/automations.md#triggers) erklärt jeden Trigger in der Sprache des Builders.

---

## Fehler

Jeder Fehler hat die übliche Form `{ "success": false, "error_code": <status>, "error": "..." }`. Ein abgelehnter Graph fügt `code` und `errors` hinzu: `errors` listet jedes Problem auf, jeweils mit einem korrigierbaren Satz, und `error` ist das erste davon. Beheben Sie genau das, was aufgelistet ist, und senden Sie den gesamten Graphen erneut. `code` ist einer der Werte `invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger` oder ein anderer Code vom Builder.

| Status | Wann |
|---|---|
| `400` | Der Graph wurde abgelehnt, ein erforderliches Feld fehlt (`name` oder `graph` beim Erstellen, `folder_id` beim Verschieben), ein Update hat nichts zum Ändern gesendet, eine ID ist nicht gültig oder ein Ordnername fehlt, ist leer oder zu lang (`code: "invalid_name"`). |
| `403` | Das Konto verfügt nicht über Automatisierungen; der Plan eines Kundenkontos beinhaltet nicht das Erstellen und Bearbeiten von Automatisierungen (nur Schreibzugriff); oder der Zugriff des Teammitglieds auf **Automatisierungen** ist zu gering. |
| `404` | Keine Automatisierung mit dieser ID in diesem Konto, kein Ordner mit dieser ID (`code: "folder_not_found"`) oder ein `sub_account_id`, das kein Kundenkonto von Ihnen ist. |
| `409` | Ein Ordner mit diesem Namen existiert bereits (`code: "folder_name_taken"`). |
| `413` | Die Automatisierung ist größer als das 1 MB, das der Builder akzeptiert. Verschieben Sie großen Code oder Daten aus ihren Schritten. |
| `422` | Der Builder hat die Anfrage aus einem anderen Grund abgelehnt. Überprüfen Sie den Graphen anhand von `GET /automations/steps`; das erneute Senden derselben Anfrage hilft nicht. |
| `503` | Der Automatisierungsdienst konnte nicht erreicht werden. Versuchen Sie es in einem Moment erneut. Listen Sie bei einer Erstellung zuerst Ihre Automatisierungen auf, damit Sie keinen zweiten Entwurf erstellen. |

::: master-only
## Verwendung dieser Endpunkte über MCP

Jeder Endpunkt auf dieser Seite ist auch ein Tool für einen KI-Assistenten, den Sie [über MCP verbinden](../integrations/connect-ai-clients.md), mit denselben Regeln: Eine neue Automatisierung ist ein Entwurf, bis sie aktiviert wird, und eine Bearbeitung an einer laufenden Automatisierung ist sofort live.

| Tool | Endpunkt |
|---|---|
| `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` |
:::

---

## Nächste Schritte

- [Automatisierungen](../automations/automations.md): Wie Trigger, Schritte, Variablen und der Ausführungsverlauf im Builder funktionieren.
- [API für Agenturen](../agency/api-for-agencies.md): Erstellen Sie Automatisierungen auf einem Kundenkonto mit `sub_account_id`.
- [API-Referenz](reference.md): Der vollständige interaktive Endpunkt-Explorer.