Übersicht der Automations-API

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 reagiert ausschließlich auf Engagement, das ein Nutzer direkt an Sie richtet (ein Kommentar, eine Story-Antwort, eine DM oder eine Reaktion) – sie sendet niemals follow-getriggerte DMs, Erstnachrichten-DMs an Fremde oder Massenversand – und erbt die Ayrshare-Ratenlimits pro Konto, die Deduplizierung pro Empfänger und die idempotente Webhook-Verarbeitung.

sent bedeutet, dass Meta die Nachricht akzeptiert hat, nicht dass der Empfänger sie erhalten hat. Die Zustellung wird letztlich durch die Instagram-Einstellung Message requests des Empfängers bestimmt: Wenn dieser keine Message Requests von allen zulässt, gibt Meta eine Erfolgsantwort zurück und verwirft die Nachricht stillschweigend – und das ist auf jeder API-Ebene unsichtbar. Selbst eine zugestellte, kommentar-getriggerte DM landet als Message Request, den der Empfänger akzeptieren muss (es sei denn, zwischen den beiden Konten besteht bereits eine Konversation). Die vollständige Erklärung finden Sie unter Automation-DM gesendet, aber nicht zugestellt.

Funktionsweise

Automatisierung erstellen

POST /automations mit den gewünschten Triggern und Aktionen. Die Automatisierung wird sofort aktiviert.

Ein Endnutzer interagiert

Jemand kommentiert Ihren Beitrag, antwortet auf Ihre Story, sendet eine DM oder reagiert auf eine DM. Meta liefert den Webhook an Ayrshare aus.

Ayrshare gleicht ab und versendet

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.

Prüfen, was ausgelöst wurde

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.	`message` (erforderlich, Template)
`fire_webhook`	Sendet den Automatisierungskontext per POST an Ihre Webhook-URL auf Kontoebene (konfigurierbar über `POST /hook/webhook`).	(keine – die Payload-Struktur ist fest; siehe unten)
`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.

Action with a 24h dedup override

{
  "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:

{
  "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 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, 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`	Mindestens eine Aktion wurde von der Plattform akzeptiert, und keine hat einen Auth-Fehler ausgelöst. Bei `send_dm` bedeutet das, dass Instagram die Nachricht akzeptiert hat – nicht, dass der Empfänger sie erhalten hat (siehe den Hinweis unten)
`failed`	Keine Aktion wurde akzeptiert und mindestens eine wurde von der Plattform abgelehnt oder konnte nicht ausgeführt werden (und keine hat einen Auth-Fehler ausgelöst). Der Grund steht in `actionResults[].errorDetails`
`auth_error`	Die Instagram-Anmeldedaten oder Messaging-Berechtigungen des Kontos konnten nicht verwendet werden – zum Beispiel ein abgelaufenes oder widerrufenes Access-Token, eine fehlende Facebook-Page-Auswahl oder für das Profil nicht aktiviertes Messaging. Die DM wurde nicht erneut versucht. Zustellfehler pro Empfänger werden als `failed` erfasst, nicht hier
`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 vor dem Versand unterdrückt – sie wurde zwischen Fan-out und Versand inaktiv oder gelöscht, sie hat keine konfigurierten Aktionen, oder das Engagement, das sie ausgelöst hat, kam von demselben Konto, das die DM senden würde – am häufigsten ein Kommentar zu einem eigenen Beitrag (ein Konto kann sich nicht selbst anschreiben)

pending und in_flight sind temporär; alles andere ist terminal. Wenn eine Automatisierung mehr als eine Aktion hat, wird der status auf oberster Ebene in dieser Reihenfolge aus den Ergebnissen pro Aktion abgeleitet: auth_error, wenn eine Aktion einen Auth-Fehler ausgelöst hat, dann sent, wenn eine Aktion akzeptiert wurde, dann deduplicated, wenn jede Aktion dedupliziert wurde, dann skipped, wenn jede Aktion bewusst unterdrückt wurde (skipped oder deduplicated), andernfalls failed. Lesen Sie actionResults[] für die Details pro Aktion.

sent ist eine Empfangsbestätigung der Plattform, keine Zustellbestätigung. Instagram legt die Nachrichtenzustellung auf keiner API offen. Eine send_dm-Aktion wird in dem Moment als sent markiert, in dem Instagram die Nachricht akzeptiert; ob der Empfänger sie tatsächlich erhält, hängt von seiner Instagram-Einstellung Message requests ab, die Ayrshare weder auslesen noch beeinflussen kann. Siehe Automation-DM gesendet, aber nicht zugestellt.

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 zuvor interagiert hat (Kommentar, Antwort, DM, Reaktion), bevor ein Business-Konto ihm eine Nachricht senden darf. Jeder unterstützte Trigger ist an eine solche Interaktion gebunden – beachten Sie aber, dass das Senden erlaubt zu sein nicht dasselbe ist wie das Zustellen der Nachricht: Die Instagram-Einstellung Message requests des Empfängers kann weiterhin dazu führen, dass Meta die Nachricht akzeptiert und dann stillschweigend verwirft (siehe Automation-DM gesendet, aber nicht zugestellt).
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

Kann ich bei einem neuen Follower auslösen?

Nein. Instagram veröffentlicht keinen Follow-Webhook, und Meta erlaubt Drittanbieter-Apps nicht, eine DM an einen Nutzer zu senden, der nicht zuvor interagiert hat. Jeder unterstützte Trigger (comment_keyword, story_reply, dm_reaction, dm_keyword) ist an eine solche Interaktion gebunden, und das ist es, was den Versand zulässig macht.

Warum sagt eine Activity `sent`, aber der Empfänger hat die DM nie erhalten?

sent bedeutet, dass Instagram die Nachricht akzeptiert hat, nicht dass sie zugestellt wurde. Die Zustellung hängt von der Instagram-Einstellung Message requests des Empfängers ab – wenn dieser keine Message Requests von allen zulässt, gibt Meta eine Erfolgsantwort zurück und verwirft die Nachricht stillschweigend, ohne Fehler, Webhook oder anderes Signal auf irgendeiner API-Oberfläche. Eine erfolgreich versendete, kommentar-getriggerte DM landet außerdem als Message Request, den der Empfänger akzeptieren muss (es sei denn, eine Konversation besteht bereits). Dies ist eine dauerhafte Einschränkung der Instagram-Plattform. Siehe Automation-DM gesendet, aber nicht zugestellt.

Was passiert, wenn mein Access-Token beim Auslösen einer Automatisierung ungültig ist?

Wenn die Instagram-Anmeldedaten oder Messaging-Berechtigungen des Kontos tatsächlich fehlschlagen – zum Beispiel ein abgelaufenes oder widerrufenes Access-Token, eine fehlende Facebook-Page-Auswahl oder für das Profil nicht aktiviertes Messaging –, erhält die Activity-Zeile den Status auth_error und die DM wird nicht wiederholt. Nachdem der Kontostatus behoben wurde (erneutes Verknüpfen, Auswahl einer Page oder Aktivierung von Messaging), wird das nächste passende Engagement normal ausgelöst. Dies gilt nur für tatsächliche Fehler bei Anmeldedaten und Berechtigungen: Konnte eine bestimmte DM aus einem anderen Grund nicht zugestellt werden – zum Beispiel, weil der Empfänger nicht gefunden werden konnte oder das auslösende Engagement von dem Konto stammt, das die DM senden würde –, wird die Zeile mit dem Grund in actionResults[].errorDetails als failed oder skipped erfasst, und erneutes Verknüpfen ändert das Ergebnis nicht.

Warum gibt es eine Verzögerung, bevor die DM gesendet wird?

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.

Werden Activity-Zeilen dauerhaft aufbewahrt?

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

Entfernt das Löschen einer Automatisierung deren Activity-Historie?

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 – eine neue Automatisierung erstellen
GET /automations – Ihre Automatisierungen auflisten
GET /automations/:id – eine Automatisierung mit ihren Triggern und Aktionen abrufen
PUT /automations/:id – Teilaktualisierung; über active: false pausieren
DELETE /automations/:id – Soft-Delete
GET /automations/:id/activity – cursor-paginiertes Versand-Audit-Log

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Funktionsweise

Trigger

Aktionen

Dedup-Fenster pro Aktion

`fire_webhook` payload

Template-Variablen

Ratenlimits und Obergrenzen

Activity-Status

Fehlercodes

Was Meta NICHT erlaubt

Nutzung mit mehreren Profilen

FAQ

Endpunkte

​Funktionsweise

​Trigger

​Aktionen

​Dedup-Fenster pro Aktion

​fire_webhook payload

​Template-Variablen

​Ratenlimits und Obergrenzen

​Activity-Status

​Fehlercodes

​Was Meta NICHT erlaubt

​Nutzung mit mehreren Profilen

​FAQ

​Endpunkte

Funktionsweise

Trigger

Aktionen

Dedup-Fenster pro Aktion

`fire_webhook` payload

Template-Variablen

Ratenlimits und Obergrenzen

Activity-Status

Fehlercodes

Was Meta NICHT erlaubt

Nutzung mit mehreren Profilen

FAQ

Endpunkte