Übersicht der Automations-API - Ayrshare API Documentation

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

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`	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

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

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

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.

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

​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