> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Übersicht der Automations-API
> Engagement-getriggerte Instagram-Automatisierungen – senden Sie eine DM, feuern Sie einen Webhook oder verschicken Sie eine E-Mail, wenn ein Endnutzer kommentiert, auf eine Story antwortet, auf eine DM reagiert oder eine DM sendet
export const PlansAvailable = ({plans = [], maxPackRequired}) => {
let displayPlans = plans;
if (plans && plans.length === 1) {
const lowerCasePlan = plans[0].toLowerCase();
if (lowerCasePlan === "business") {
displayPlans = ["Launch", "Business", "Enterprise"];
} else if (lowerCasePlan === "premium") {
displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
}
}
return
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.
{maxPackRequired && window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
Max Pack required
}
;
};
**Beta.** Die Automations-API befindet sich in der Beta-Phase und wir sammeln aktiv Feedback. Endpunkte, Payloads und Limits können sich im Laufe der Iterationen ändern. Bitte senden Sie Feedback und Fehlerberichte an den Support, damit wir die richtigen Verbesserungen priorisieren können.
Mit den Automations-Endpunkten können Sie Regeln definieren, die automatisch auf eingehendes Instagram-Engagement reagieren. Jede Automatisierung koppelt einen oder mehrere **Trigger** (das Ereignis, das die Regel auslöst) mit einer oder mehreren **Aktionen** (was passiert, wenn die Regel ausgelöst wird). Eine einzelne Regel kann auf mehrere Trigger hören und mehrere Aktionen ausführen – etwa gleichzeitig einen Webhook an Ihre Analytics-Pipeline feuern UND aus demselben Engagement eine DM senden.
Die Engine läuft vollständig innerhalb der Richtlinien von Meta (keine DMs bei neuen Followern, keine Erstnachrichten an Fremde, kein Massenversand) und erbt die Ayrshare-Ratenlimits pro Konto, die Deduplizierung pro Empfänger und die idempotente Webhook-Verarbeitung.
## Funktionsweise
`POST /automations` mit den gewünschten Triggern und Aktionen. Die Automatisierung wird sofort aktiviert.
Jemand kommentiert Ihren Beitrag, antwortet auf Ihre Story, sendet eine DM oder reagiert auf eine DM. Meta liefert den Webhook an Ayrshare aus.
Die Engine sucht jede Regel, die zum Ereignis passt, prüft die Deduplizierung pro Aktion sowie Ihr tägliches DM-Limit und führt anschließend jede Aktion aus. Beim Senden von DMs wird ein Jitter von 20–60 Sekunden angewendet, um innerhalb der Anti-Spam-Heuristiken von Instagram zu bleiben.
`GET /automations/:id/activity` gibt das Audit-Log zurück – jeden Versendungsversuch, die Ergebnisse pro Aktion und etwaige Fehler.
## Trigger
Sie können einer Automatisierung bis zu **50 Trigger** hinzufügen. Jeder Trigger ist eine Discriminated Union über das Feld `type`; typspezifische Felder befinden sich auf derselben Ebene. Alle Trigger sind in v1 ausschließlich für Instagram verfügbar.
| Typ | Wird ausgelöst, wenn | Konfiguration |
| ----------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `comment_keyword` | Ein Kommentar mit passendem Schlüsselwort auf einem bestimmten Beitrag eingeht | `postId` (erforderlich); `keywords` (erforderlich, ≥1 Eintrag) |
| `story_reply` | Ein Nutzer per DM auf eine Story antwortet | `storyId` (optional) |
| `dm_reaction` | Ein Nutzer mit einem Emoji auf eine Ihrer DMs reagiert | `emoji` (optional – weglassen, um auf jedes Emoji zu reagieren) |
| `dm_keyword` | Ein Nutzer eine DM sendet, deren Text zu einem Schlüsselwort passt | `keywords` (erforderlich, ≥1 Eintrag) |
Der Abgleich von Schlüsselwörtern erfolgt **ohne Berücksichtigung der Groß-/Kleinschreibung** und wortweise. Ein Ereignis erfüllt einen keyword-gefilterten Trigger, wenn es eines der konfigurierten Schlüsselwörter enthält. Lassen Sie `storyId` bei einem Story-Trigger weg, um bei jeder Story des verbundenen Kontos auszulösen.
## Aktionen
Sie können einer Automatisierung bis zu **50 Aktionen** hinzufügen. Sie werden sequentiell ausgeführt; jedes Ergebnis wird in der Activity-Zeile festgehalten.
| Typ | Wirkung | Konfiguration |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `send_dm` | Sendet eine Instagram-DM an den Nutzer, der die Regel ausgelöst hat, unter Verwendung einer [Template-Nachricht](#template-variables). | `message` (erforderlich, Template) |
| `fire_webhook` | Sendet den Automatisierungskontext per POST an Ihre Webhook-URL auf Kontoebene (konfigurierbar über [`POST /hook/webhook`](/apis/webhooks/register)). | *(keine – die Payload-Struktur ist fest; siehe [unten](#fire_webhook-payload))* |
| `send_email` | Stellt eine E-Mail über die Mail-Pipeline der Plattform in die Warteschlange. | `to` (erforderlich, E-Mail); `subject` (optional, Template); `message` (erforderlich, Template) |
### Dedup-Fenster pro Aktion
Jede Aktion – unabhängig vom Typ – akzeptiert zusätzlich ein optionales Feld `dedupWindowMinutes` auf oberster Ebene, das das **standardmäßige 7-Tage-Dedup-Fenster** pro Empfänger nur für diese Aktion überschreibt.
* Setzen Sie den Wert auf `0`, um die Deduplizierung für diese Aktion vollständig zu **deaktivieren** (üblich bei `fire_webhook` / `send_email`, wenn der Empfänger jedes Ereignis erwartet).
* Auf `525600` (ein Jahr) begrenzt.
```json Action with a 24h dedup override theme={"system"}
{
"type": "send_dm",
"message": "Thanks {{recipient_username}}!",
"dedupWindowMinutes": 1440
}
```
### `fire_webhook` payload
Wenn `fire_webhook` ausgeführt wird, sendet es einen JSON-Body per POST an Ihre Webhook-URL auf Kontoebene:
```json theme={"system"}
{
"automationId": "auto_9xKp2Lm4nQ",
"triggerId": "trg_a1b2c3",
"trigger": "comment_keyword",
"platform": "instagram",
"recipientId": "17841401234567890",
"recipientUsername": "jane_doe",
"keyword": "LINK",
"timestamp": "2026-05-12T09:14:22.000Z"
}
```
`recipientUsername` und `keyword` sind `null`, wenn der Trigger sie nicht befüllt (z. B. enthält `dm_keyword` in der Meta-Payload keinen Benutzernamen; `story_reply` hat kein Schlüsselwort).
## Template-Variablen
`send_dm.message`, `send_email.subject` und `send_email.message` unterstützen `{{placeholder}}`-Substitution. **Unbekannte Platzhalter werden beim Erstellen/Aktualisieren abgelehnt** (als Validierungsfehler `473`), sodass ein Tippfehler nie unbemerkt das wörtliche `{{foo}}` in eine an Kunden gerichtete Nachricht durchsickern lässt.
| Platzhalter | Wird aufgelöst zu |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `{{recipient_username}}` | Instagram-Handle des interagierenden Nutzers (sofern der Webhook es liefert) |
| `{{recipient_id}}` | Instagram Participant ID (IGSID) des interagierenden Nutzers |
| `{{recipient_name}}` | Reserviert; wird zu einem leeren Wert aufgelöst, bis eine zukünftige Anreicherungsquelle den Wert liefert |
| `{{sender_username}}` | Ihr verknüpfter Instagram-Benutzername |
| `{{sender_name}}` | Ihr verknüpfter Instagram-Anzeigename |
| `{{comment_text}}` | Text des Kommentars / der DM / der Story-Antwort, der den Trigger ausgelöst hat |
| `{{comment_id}}` | Plattform-ID des Kommentars / der Nachricht, der/die ausgelöst hat |
| `{{comment_sent_at}}` | ISO-8601-Zeitstempel des Ereignisses (sofern verfügbar) |
| `{{matched_keyword}}` | Das passende Schlüsselwort (oder der Emoji-String bei `dm_reaction`) |
| `{{platform}}` | Plattformkennung (z. B. `instagram`) |
| `{{trigger_type}}` | Trigger-Typ (z. B. `comment_keyword`) |
**Kein `sender_email` / `recipient_email`.** Diese werden bewusst nicht bereitgestellt – Ihre Abrechnungs-E-Mail hat in einer DM an einen Fremden nichts zu suchen, und Meta liefert die E-Mail-Adresse des Empfängers in keinem IG-Webhook. Der Verzicht auf die Platzhalter verhindert eine versehentliche Offenlegung.
Beispiel-Template:
```
Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com
```
## Ratenlimits und Obergrenzen
| Plan | Aktive Automatisierungen (pro Profil) | Tägliches DM-Limit (pro Konto) |
| ---------- | ------------------------------------- | ------------------------------ |
| Business | 10 | 1.000 |
| Enterprise | 50 | 5.000 |
Die Obergrenze für aktive Automatisierungen wird **pro [User Profile](/apis/profiles/overview)** gezählt, nicht pro übergeordnetem Konto. Jedes Profil unter Ihrem Konto erhält seine eigenen Business-10-/Enterprise-50-Werte, sodass ein Konto mit vielen Profilen entsprechend viele Automatisierungen je Profil betreiben kann. Gezählt werden aktive Automatisierungen; die Grenze wird sowohl bei `POST` (Erstellung) als auch bei `PUT`-Reaktivierung (`active: false → true`) durchgesetzt und liefert jeweils den Fehlercode `470`. Benötigen Sie ein höheres Limit pro Profil? [Kontaktieren Sie den Support](mailto:support@ayrshare.com), um es für Ihr Konto anheben zu lassen.
Das **tägliche DM-Limit** gilt pro übergeordnetem Ayrshare-Konto und wird über alle Ihre Profile hinweg geteilt, mit einem Unterlimit pro Profil, sodass ein besonders aktives Profil das Kontingent des gesamten Kontos nicht aufbrauchen kann. Wird ein DM-Limit erreicht, erhält die Activity-Zeile den Status `rate_limited` und es wird keine DM gesendet.
Strukturelle Obergrenzen einer einzelnen Automatisierung: **1–50 Trigger**, **1–50 Aktionen**.
Instagram selbst begrenzt DMs auf etwa 200/Stunde pro Konto. Die Engine drosselt den Versand mit einem Jitter von 20–60 Sekunden, um sicher unter diesem Wert zu bleiben.
## Activity-Status
Eine Zeile in `GET /automations/:id/activity` enthält einen `status` auf oberster Ebene sowie einen `status` pro Aktion innerhalb von `actionResults[]`:
| Status | Bedeutung |
| -------------- | ----------------------------------------------------------------------------------------- |
| `pending` | Gerade geschrieben; der Worker hat sie noch nicht aufgenommen |
| `in_flight` | Der Worker versendet gerade |
| `sent` | Jede Aktion war erfolgreich |
| `failed` | Mindestens eine Aktion ist fehlgeschlagen (und keine hat einen Auth-Fehler ausgelöst) |
| `auth_error` | Das Instagram-Access-Token war ungültig; die DM wurde nicht erneut versucht |
| `rate_limited` | Das tägliche DM-Limit (Tarif oder pro Profil) wurde erreicht; es wurde keine DM gesendet |
| `deduplicated` | Diese Aktion wurde für diesen Empfänger bereits innerhalb ihres Dedup-Fensters ausgeführt |
| `skipped` | Die Automatisierung wurde zwischen Fan-out und Versand inaktiv oder gelöscht |
`pending` und `in_flight` sind temporär; alles andere ist terminal.
## Fehlercodes
Die API gibt zwei Fehlerformen zurück:
* **Business-Regel-Fehler** tragen einen nummerierten Automatisierungs-`code` (z. B. `{ "action": "automation", "code": 469, ... }`).
* **Validierungsfehler** – jeder fehlerhafte Request-Body (fehlende oder ungültige Felder, unbekannte Template-Variablen, unbekannte Schlüssel) – werden als einzelne **`473`**-Antwort mit einem `details`-Objekt zurückgegeben, das die beanstandeten Felder auflistet. `details` ist die Ausgabe des Validators (`formErrors` sowie `fieldErrors`). Verzweigen Sie anhand von `details`, nicht anhand eines bedingungsspezifischen Codes. In `fieldErrors` sind die Schlüssel die Top-Level-Request-Felder (`triggers`, `actions`): Ein Problem innerhalb eines bestimmten Eintrags, etwa ein Trigger ohne `keywords`, wird unter diesem Feld (z. B. `triggers`) gemeldet, während `formErrors` Probleme auf Objektebene wie unbekannte Schlüssel enthält.
| Code | HTTP | Bedeutung |
| ---- | ---- | ----------------------------------------------------------------------------------- |
| 468 | 403 | Business- oder Enterprise Plan erforderlich |
| 469 | 404 | Automatisierung nicht gefunden (auch wenn der Aufrufer nicht Eigentümer ist) |
| 470 | 429 | Obergrenze für aktive Automatisierungen Ihres Plans erreicht |
| 471 | 400 | Kein Social-Konto für die angefragte Plattform in diesem Profil verknüpft |
| 472 | 403 | Funktion für Ihr Konto noch nicht verfügbar – kontaktieren Sie uns für Early Access |
| 473 | 400 | Validierung fehlgeschlagen (fehlerhafter Request-Body) – siehe `details` |
## Was Meta NICHT erlaubt
Einige häufig nachgefragte Funktionen werden nicht unterstützt, weil Meta sie in der öffentlichen Instagram-API nicht zulässt:
* **Auto-DM bei neuen Followern.** Instagram veröffentlicht keinen Follow-Webhook.
* **Erstnachrichten-DMs an Fremde.** Meta verlangt, dass der Empfänger den Kontakt zuerst aufnimmt (Kommentar, Antwort, DM, Reaktion), bevor ein Business-Konto ihm eine Nachricht senden darf – genau das repräsentiert jeder hier unterstützte Trigger.
* **Bulk-Outbound-Kampagnen.** Stündliche DM-Limits und Anti-Missbrauch-Heuristiken gelten auf Plattformebene.
## Nutzung mit mehreren Profilen
Die Endpunkte berücksichtigen den Header `profileKey`. Übergeben Sie den Schlüssel eines untergeordneten Profils, und die Automatisierung wird unter diesem Profil erstellt/verwaltet. Ratenlimits werden über ein Unterlimit pro Profil auf die Profile aufgeteilt, sodass ein besonders gesprächiges Profil das Kontingent des übergeordneten Kontos nicht aufbraucht.
## FAQ
Nein. Instagram veröffentlicht keinen Follow-Webhook, und Meta erlaubt Drittanbieter-Apps nicht, eine DM an einen Nutzer zu senden, der noch keine Konversation initiiert hat. Jeder unterstützte Trigger (`comment_keyword`, `story_reply`, `dm_reaction`, `dm_keyword`) erfüllt die Anforderung „Nutzer hat Sie zuerst kontaktiert".
Die Activity-Zeile erhält den Status `auth_error` und die DM wird nicht wiederholt. Verknüpfen Sie das Konto erneut; das nächste passende Engagement wird dann normal ausgelöst.
Jeder `send_dm`-Versand wird 20–60 Sekunden nach dem Engagement geplant, damit er für die Anti-Spam-Systeme von Instagram organisch wirkt. Die Aktionen `fire_webhook` und `send_email` haben KEINEN Jitter. Der `created`-Zeitstempel der Activity-Zeile entspricht dem Zeitpunkt des Trigger-Matches; `completedAt` entspricht dem Abschluss des Versands.
Activity-Zeilen werden für Tracing und Analytics unbegrenzt aufbewahrt. Der Endpunkt `GET /automations/:id/activity` gibt aus Performance-Gründen Zeilen der letzten 30 Tage zurück. (Der Dedup-Schutz nutzt sein eigenes Fenster pro Aktion – standardmäßig 7 Tage – das mit dem Activity-Rückblick nichts zu tun hat.)
Nein. Das Löschen erfolgt als Soft-Delete: Die Master-Zeile wird als `deleted` markiert, es werden keine neuen Versendungen ausgeführt, aber historische Activity-Zeilen bleiben über den Activity-Endpunkt lesbar.
## Endpunkte
* [`POST /automations`](/apis/automations/create-automation) – eine neue Automatisierung erstellen
* [`GET /automations`](/apis/automations/list-automations) – Ihre Automatisierungen auflisten
* [`GET /automations/:id`](/apis/automations/get-automation) – eine Automatisierung mit ihren Triggern und Aktionen abrufen
* [`PUT /automations/:id`](/apis/automations/update-automation) – Teilaktualisierung; über `active: false` pausieren
* [`DELETE /automations/:id`](/apis/automations/delete-automation) – Soft-Delete
* [`GET /automations/:id/activity`](/apis/automations/get-activity) – cursor-paginiertes Versand-Audit-Log