Ü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 Engagement auf Instagram und auf DMs an Facebook-Seiten 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. Auf Instagram wird die Zustellung letztlich durch die 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

Auf das Engagement wird ein Jitter von 20–60 Sekunden angewendet, um innerhalb der Anti-Spam-Heuristiken von Instagram zu bleiben. Danach sucht die Engine jede Regel, die zum Ereignis passt, prüft die Deduplizierung pro Aktion sowie Ihr tägliches DM-Limit und führt jede Aktion aus.

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. Die Spalte Plattformen zeigt, wo jeder Trigger verfügbar ist; unter Facebook-Seiten erfahren Sie, was Facebook voraussetzt.

Typ	Wird ausgelöst, wenn	Plattformen	Konfiguration
`comment_keyword`	Ein Kommentar mit passendem Schlüsselwort auf einem Beitrag oder Reel eingeht	`instagram`	`postId` (erforderlich – eine Beitrags-ID oder `"all"`); `keywords` (erforderlich, ≥1 Eintrag)
`story_reply`	Ein Nutzer per DM auf eine Story antwortet	`instagram`	`storyId` (optional – eine Story-ID oder `"all"`)
`dm_reaction`	Ein Nutzer mit einem Emoji auf eine Ihrer DMs reagiert	`instagram`, `facebook`	`emoji` (optional – weglassen, um auf jedes Emoji zu reagieren)
`dm_keyword`	Ein Nutzer eine DM sendet, deren Text zu einem Schlüsselwort passt	`instagram`, `facebook`	`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.

Evergreen-Regeln mit `"all"`

Setzen Sie postId (oder storyId) auf den wörtlichen kleingeschriebenen String "all", um bei jedem Beitrag, Reel oder jeder Story des verbundenen Kontos auszulösen statt bei einem bestimmten Inhalt. Das ist genau das Richtige für eine Regel, die weiterarbeiten soll, während neue Inhalte veröffentlicht werden, ohne einen API-Aufruf pro Beitrag:

{
  "type": "comment_keyword",
  "postId": "all",
  "keywords": ["LINK", "INFO"]
}

Der Wert muss exakt "all" lauten. Eine Variante wie "ALL" oder " all" wird mit einem Validierungsfehler abgelehnt, statt als Beitrags-ID gespeichert zu werden, die nie zu einem Match führen würde. "all" reicht nie über das verbundene Konto hinaus – eine Regel auf einem Profil kann nicht auf den Inhalten eines anderen Profils auslösen. Ihr tägliches DM-Limit und die an das Engagement gebundenen Versandregeln gelten genau wie bei einer Regel für einen einzelnen Beitrag.

Die Deduplizierung wird pro Automatisierung und Empfänger gezählt, nicht pro Beitrag. Bei einer "all"-Regel erhält ein Nutzer, der innerhalb des Dedup-Fensters (standardmäßig 7 Tage) ein Schlüsselwort auf zwei verschiedenen Beiträgen kommentiert, die DM nur einmal; die zweite Activity wird als deduplicated erfasst. Ein kleineres dedupWindowMinutes verkürzt nur dieses Fenster; es macht die Deduplizierung nicht pro Beitrag. Der Wert 0 deaktiviert die Deduplizierung, sodass jeder passende Kommentar eine DM sendet, einschließlich wiederholter Kommentare auf demselben Beitrag.

Bei den Story-Triggern verhält sich das Weglassen von storyId genauso wie "all". Bevorzugen Sie "all" – es macht die Absicht explizit, und das Weglassen wird in einer zukünftigen Version eingestellt, mit vorheriger Ankündigung unter Upcoming API Changes.

Facebook-Seiten

Setzen Sie platform auf facebook, um eine Automatisierung auf der Facebook-Seite auszuführen, die mit dem Profil verknüpft ist. DMs werden von der Seite über Messenger gesendet.

Trigger: dm_keyword und dm_reaction. Kommentar- und Story-Trigger sind vorerst ausschließlich für Instagram verfügbar, und eine Facebook-Automatisierung, die einen davon verwendet, wird mit einem Validierungsfehler abgelehnt.
Messaging: Für das Profil muss Messaging für Facebook aktiviert sein, genauso wie beim Senden einer Facebook-DM mit der Messages API.
Empfänger: {{recipient_id}} ist die Page-scoped ID (PSID) des Nutzers. {{recipient_username}} ist leer, weil Messenger-Webhooks keinen Nutzernamen enthalten.

{
  "platform": "facebook",
  "name": "Price list on request",
  "triggers": [{ "type": "dm_keyword", "keywords": ["price"] }],
  "actions": [{ "type": "send_dm", "message": "Here is our price list: https://example.com/prices" }]
}

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 DM (auf Instagram oder über Messenger von Ihrer Facebook-Seite) an den Nutzer, der die Regel ausgelöst hat, unter Verwendung einer Template-Nachricht oder eines Texts, den Sie pro Auslösung generieren.	`message` (erforderlich, Template); `messageUrl` (optional); `timeoutMs` (optional)
`fire_webhook`	Sendet den Automatisierungskontext per POST an Ihre Webhook-URL auf Kontoebene (konfigurierbar über `POST /hook/webhook`).	`sendCompletedEvent` (optional, Boolean – sendet zusätzlich `automation.completed`). 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
}

Dynamischer Nachrichteninhalt

Standardmäßig sendet send_dm dieselbe message an alle, die die Regel auslösen. Platzhalter wie {{recipient_username}} sind der einzige Teil, der sich von Person zu Person ändert. Setzen Sie stattdessen messageUrl auf der Aktion, schreibt Ihr eigener Server die DM für jede Person: Jedes Mal, wenn die Regel greift, fragen wir Ihren Endpunkt, was gesagt werden soll, und senden seine Antwort als DM. Beispiel. Ihre Regel antwortet allen, die unter einem Beitrag „LINK“ kommentieren, und messageUrl zeigt auf Ihren Server. Wenn Ava „LINK please!“ kommentiert:

Wir senden die Details per POST an Ihre messageUrl: wer kommentiert hat ("recipientUsername": "ava"), was geschrieben wurde und unter welchem Beitrag.
Ihr Server schreibt eine Antwort für Ava, zum Beispiel mit einem eigens für sie erstellten Tracking-Link, und antwortet mit { "message": "Hi ava, here's your link: https://example.com/r/12345" }.
Wir senden diesen Text als DM an Ava, genau so, wie Sie ihn geschrieben haben.

Wenn Ihr Server nicht innerhalb von timeoutMs antwortet, einen Fehler zurückgibt oder etwas zurückgibt, das wir nicht verwenden können, senden wir Ava stattdessen die reguläre message der Aktion, sodass sie trotzdem eine Antwort erhält. Fügen Sie es einer send_dm-Aktion wie folgt hinzu:

send_dm with messageUrl

{
  "type": "send_dm",
  "messageUrl": "https://yourapp.example.com/automations/message",
  "timeoutMs": 3000,
  "message": "Thanks for commenting! Here is the link: https://example.com"
}

messageUrl ist die Adresse, bei der wir den Text anfragen. message ist weiterhin erforderlich und dient als Fallback: Sie wird nie an Ihren Server gesendet, und wir verschicken sie stattdessen als DM, wann immer Ihr Server nicht rechtzeitig antwortet, einen Fehler zurückgibt oder etwas zurückgibt, das wir nicht verwenden können (siehe die Warnung unten). timeoutMs ist optional (Standard 3000, Maximum 5000). Was wir an Ihren Endpunkt senden. Einen POST mit diesem JSON-Body:

Callback request body

{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "ava",
  "keyword":           "LINK",
  "activityId":        "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "actionId":          "act_dm_1",
  "eventId":           "comment.received:17912345678901234",
  "commentId":         "17912345678901234",
  "commentText":       "LINK please!",
  "postId":            "17998765432109876",
  "storyId":           null,
  "timestamp":         "2026-05-12T09:14:22.000Z",
  "timeStamp":         1778577262
}

Feld	Bedeutung
`automationId`, `triggerId`, `trigger`, `platform`	Welche Automatisierung und welcher Trigger ausgelöst wurden, wie in der `fire_webhook`-Payload
`recipientId`, `recipientUsername`	Die Person, an die die DM geht. `recipientUsername` ist `null`, wenn der Trigger keinen Nutzernamen mitliefert (zum Beispiel `dm_keyword`)
`keyword`	Das Schlüsselwort, das gematcht hat, oder `null`
`activityId`	Der Activity-Eintrag für diese Auslösung, sodass Sie ihn mit `GET /automations/:id/activity` abgleichen können
`actionId`	Welche `send_dm`-Aktion anfragt, entsprechend `actionResults[].actionId`. Damit kann ein Endpunkt mehrere `send_dm`-Aktionen derselben Automatisierung bedienen
`eventId`	Unsere ID für das Engagement, das die Auslösung verursacht hat
`commentId`	Die Instagram-Kommentar-ID bei Kommentar-Triggern; `null` bei DM- und Story-Triggern
`commentText`	Der Text, der gematcht hat: der Kommentar, die DM oder das Reaktions-Emoji. `null`, wenn es keinen gibt (zum Beispiel `story_reply`)
`postId`, `storyId`	Der Beitrag oder die Story, auf die sich das Engagement bezieht, oder `null`
`timestamp`	Wann wir die Anfrage gestellt haben, im Format ISO 8601
`timeStamp`	Derselbe Zeitpunkt als Unix-Zeit in Sekunden. Nur vorhanden, wenn der Callback signiert ist, wie bei unseren Webhooks

Wenn Sie ein Webhook-Secret registriert haben, wird der Body mit demselben Secret wie Ihre automations-Webhooks und auf dieselbe Weise signiert: X-Authorization-Content-SHA256 ist der HMAC-SHA256 des Roh-Bodys, und X-Authorization-Timestamp enthält den timeStamp des Bodys. Der Verifizierungscode, den Sie bereits für unsere Webhooks verwenden, funktioniert unverändert. Wenn ein Secret registriert ist, wir es in dem Moment aber nicht lesen können, senden wir den Callback nicht unsigniert, sondern stattdessen Ihr message-Template. Wohin sie zeigen darf. messageUrl muss eine öffentliche HTTPS-Adresse sein. Eine URL, die auf eine private, Loopback-, Link-Local- oder Cloud-Metadata-Adresse auflöst, wird abgelehnt, und Weiterleitungen werden nicht verfolgt – eine 3xx-Antwort gilt als Fehlschlag. In beiden Fällen wird stattdessen das Template gesendet. Was Ihr Endpunkt zurücksendet. Geben Sie 200 mit einem JSON-Body von höchstens 16 KB zurück, der einen message-String mit 1 bis 1000 Zeichen enthält:

{ "message": "Hi ava — grabbed that link for you: https://example.com/r/12345" }

Ihr Text wird wortwörtlich gesendet. Die {{placeholder}}-Substitution wird darauf nicht angewendet, sodass ein wörtliches {{ in Ihrem generierten Text den Empfänger so erreicht, wie es geschrieben ist.

message bleibt erforderlich und ist keine Dekoration. Wenn Ihr Endpunkt in ein Timeout läuft, einen Nicht-2xx-Status zurückgibt, einen Body zurückgibt, den wir nicht verwenden können, oder nach wiederholten Fehlschlägen vorübergehend per Circuit Breaker gesperrt wurde, senden wir stattdessen das gerenderte message-Template. Dieser Versand kann trotzdem fehlschlagen, zum Beispiel wenn das Template leer gerendert wird (siehe unten) oder Instagram es ablehnt. Wir wiederholen den Callback nie – eine Wiederholung riskiert, dass der Empfänger zwei Nachrichten erhält.

timeoutMs ist standardmäßig 3000. Das Maximum ist 5000: Ein größerer Wert wird beim Erstellen oder Aktualisieren der Automatisierung mit einem Validierungsfehler abgelehnt. Er deckt den gesamten Austausch ab, einschließlich des Lesens Ihres Antwort-Bodys. Planen Sie ihn ein: Die DM wird gesendet, nachdem Ihr Endpunkt geantwortet hat, sodass ein langsamer Endpunkt die Nachricht verzögert. Welchen Weg eine Auslösung genommen hat, sehen Sie unter GET /automations/:id/activity. Ein send_dm-Eintrag in actionResults[] enthält messageSource, sobald der DM-Text feststeht, auch wenn der Versand anschließend fehlgeschlagen ist. Es fehlt, wenn die Aktion vorher beendet wurde, zum Beispiel bei einer skipped-DM an Ihr eigenes Konto oder einer deduplicated-Aktion:

`messageSource`	Bedeutung
`template`	Keine `messageUrl` konfiguriert; die statische `message` wurde verwendet
`callback`	Ihr Endpunkt hat geantwortet und sein Text wurde verwendet
`fallback`	`messageUrl` war gesetzt, aber nicht verwendbar; stattdessen wurde `message` verwendet

messageSource gibt an, aus welchem Text die DM erstellt wurde, nicht, ob sie zugestellt wurde. Lesen Sie dafür den status des Eintrags. Ein Fallback allein lässt die Aktion nicht fehlschlagen: Wenn die Template-DM zugestellt wird, ist der Eintrag sent, mit dem Grund, warum der Callback nicht verwendet wurde, in errorDetails. Schlägt anschließend auch die Template-DM fehl, ist der Eintrag failed, und errorDetails enthält den Sendefehler, gefolgt vom Callback-Grund. Achten Sie darauf: Ein Callback, der bei jeder Auslösung fehlschlägt, sieht sonst genauso aus wie einer, der funktioniert. Sorgen Sie dafür, dass Ihre message auch für sich allein versendbar ist. Wenn sie für einen Empfänger leer gerendert wird, zum Beispiel {{recipient_username}} allein bei einem DM-Trigger, der keinen Nutzernamen mitliefert, und Ihr Callback-Text nicht verwendet wird, wird keine DM gesendet, und die Aktion ist failed, mit dem Grund in errorDetails.

Webhook-Ereignisse

An die automations-Webhook-Aktion, die Sie mit POST /hook/webhook registrieren, werden zwei Ereignisse ausgeliefert. Beide tragen ein type-Feld – verzweigen Sie anhand dieses Felds, bevor Sie irgendetwas anderes lesen.

`type`	Gesendet, wenn
`automation.triggered`	Die `fire_webhook`-Aktion der Regel ausgeführt wird
`automation.completed`	Der Versand abgeschlossen ist, mit seinem Ergebnis

automation.completed ist standardmäßig deaktiviert. Aktivieren Sie es für eine Automatisierung, indem Sie "sendCompletedEvent": true auf ihrer fire_webhook-Aktion setzen. Andernfalls bleibt es deaktiviert, sodass ein Empfänger, der für eine Payload pro Auslösung gebaut ist, weiterhin genau eine erhält. automation.triggered ist keine Aufzeichnung jedes Matches: Es wird nur gesendet, wenn fire_webhook selbst ausgeführt wird, sodass ein Match, das mit rate_limited oder deduplicated endet, ausschließlich automation.completed erzeugt. Keines der beiden Ereignisse wird für eine Automatisierung gesendet, die vor dem Versand deaktiviert oder gelöscht wurde.

`automation.triggered`

{
  "type":              "automation.triggered",
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "activityId":        "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "actionId":          "act_wh_1",
  "eventId":           "comment.received:17912345678901234",
  "commentId":         "17912345678901234",
  "commentText":       "LINK please",
  "postId":            "17895695668004550",
  "storyId":           null,
  "timestamp":         "2026-05-12T09:14:22.000Z"
}

activityId ist die Zeile, die GET /automations/:id/activity zurückgibt, sodass Sie beide exakt verknüpfen können, statt über recipientId + triggerId + keyword abzugleichen – was mehrdeutig ist, wenn mehrere Personen gleichzeitig dasselbe Schlüsselwort kommentieren. actionId ist die fire_webhook-Aktion, die das Ereignis gesendet hat, und entspricht actionResults[].actionId; damit lassen sich zwei fire_webhook-Aktionen derselben Regel unterscheiden. Felder, die ein Trigger nicht befüllt, sind null statt weggelassen, sodass die Struktur stabil bleibt. recipientUsername ist null bei dm_keyword, dm_reaction und story_reply, weil die Meta-Payload keinen Benutzernamen enthält. commentId ist nur bei comment_keyword und story_comment gesetzt, postId nur bei comment_keyword und storyId nur bei den Story-Triggern. story_reply hat kein keyword. Bei dm_keyword ist commentText der DM-Text; bei dm_reaction sind commentText und keyword beide das Reaktions-Emoji.

`automation.completed`

Wird nur gesendet, wenn die Automatisierung dies über ihre fire_webhook-Aktion aktiviert:

fire_webhook action with the outcome event on

{
  "type": "fire_webhook",
  "sendCompletedEvent": true
}

{
  "type":         "automation.completed",
  "automationId": "auto_9xKp2Lm4nQ",
  "triggerId":    "trg_a1b2c3",
  "trigger":      "comment_keyword",
  "platform":     "instagram",
  "recipientId":  "17841401234567890",
  "activityId":   "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:17912345678901234",
  "eventId":      "comment.received:17912345678901234",
  "status":       "sent",
  "actionResults": [
    { "actionId": "act_dm_1", "type": "send_dm",      "status": "sent", "errorDetails": null, "messageSource": "callback" },
    { "actionId": "act_wh_1", "type": "fire_webhook", "status": "sent", "errorDetails": null }
  ],
  "errorDetails": null,
  "timestamp":    "2026-05-12T09:14:58.000Z"
}

status und jedes actionResults[].status verwenden dieselben Werte wie das Activity-Log – sent, failed, rate_limited, deduplicated, skipped, auth_error –, sodass Sie im Normalfall erfahren, wie ein Versand geendet hat, ohne zu pollen. Die Zustellung dieses Ereignisses erfolgt allerdings nach dem Best-Effort-Prinzip: Wenn der Prozess zwischen dem Festhalten des Ergebnisses und dem Einreihen des Ereignisses stoppt, wird es nicht gesendet. Das Activity-Log ist die maßgebliche Aufzeichnung; wenn Sie also jedes Ergebnis benötigen, gleichen Sie für jede activityId, die noch keines gemeldet hat, gegen GET /automations/:id/activity ab. Ein send_dm-Ergebnis enthält außerdem messageSource, wie im Activity-Log: template, callback oder fallback, sodass Sie eine messageUrl, die immer wieder auf den Fallback zurückfällt, erkennen können, ohne zu pollen. Ordnen Sie Ergebnisse Ihren konfigurierten Aktionen über actionId zu, nicht über die Position – zwei Aktionen desselben Typs lassen sich nur so unterscheiden. actionResults ist in drei Fällen leer, jeweils mit dem Grund im errorDetails auf oberster Ebene, sofern es einen gibt: rate_limited (Ihr Tageslimit wurde erreicht), deduplicated (jede Aktion befand sich innerhalb ihres Dedup-Fensters) und failed, nachdem der Versand die maximale Anzahl von Wiederholungen erreicht hat, ohne abzuschließen. Im letzten Fall können einige Aktionen bereits ausgeführt worden sein, sodass eine DM möglicherweise bereits versendet und automation.triggered möglicherweise bereits gesendet wurde. Die Webhook-Zustellung erfolgt nach dem At-least-once-Prinzip, dasselbe Ereignis kann also gelegentlich zweimal eintreffen, und ein Versand, der wiederholt wird, kann automation.triggered erneut mit einer neuen hookId senden. Deduplizieren Sie niemals anhand von hookId. Verwenden Sie für jeden Ereignistyp einen eigenen Schlüssel, damit die Verarbeitung des einen niemals das andere unterdrückt: automation.completed anhand von activityId (jede Activity hat genau ein Ergebnis) und automation.triggered anhand von activityId plus actionId (eines pro fire_webhook-Aktion). Die beiden Ereignisse werden unabhängig voneinander zugestellt, sodass automation.completed gelegentlich vor automation.triggered eintreffen kann.

Wenn kein Webhook registriert ist

fire_webhook sendet per POST an die auf dem Profil registrierte automations-Aktion und fällt auf Ihr Primary Profile zurück. Es gibt keinen Fallback auf eine andere Aktion wie messages. Existiert keine der beiden Registrierungen, wird automation.triggered nicht stillschweigend verworfen: Die Aktion wird in der Activity-Zeile als failed erfasst, mit dem Grund in actionResults[].errorDetails. (automation.completed hat ebenfalls kein Ziel und wird nicht erfasst.) Der Gesamtstatus des Versands folgt dann der üblichen Rangfolge: auth_error, wenn eine Aktion einen Auth-Fehler ausgelöst hat, andernfalls sent, wenn eine Aktion akzeptiert wurde, andernfalls failed. Der fehlende Webhook zählt also nur dann zu den Fehlerstatistiken der Automatisierung, wenn sonst nichts auf der Regel gesendet hat; hat eine andere Aktion gesendet (und keine einen Auth-Fehler ausgelöst), endet der Versand mit sent und der fehlgeschlagene Webhook erscheint nur in actionResults[]. Ein fire_webhook-Ergebnis von sent bedeutet, dass das Ereignis zur Zustellung an Ihre URL eingereiht wurde, nicht dass Ihr Endpunkt es akzeptiert hat. Die Zustellung wird anschließend nach eigenem Zeitplan wiederholt.

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 bei Kommentar-Triggern. Leer bei DM- und Story-Antwort-Triggern und immer auf Facebook
`{{recipient_id}}`	ID des interagierenden Nutzers: die Instagram-scoped ID (IGSID) auf Instagram, die Page-scoped ID (PSID) auf Facebook
`{{recipient_name}}`	Reserviert; wird zu einem leeren Wert aufgelöst, bis eine zukünftige Anreicherungsquelle den Wert liefert
`{{sender_username}}`	Reserviert; wird derzeit auf allen Plattformen zu einem leeren Wert aufgelöst
`{{sender_name}}`	Reserviert; wird derzeit auf allen Plattformen zu einem leeren Wert aufgelöst
`{{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: `instagram` oder `facebook`
`{{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)
Launch & 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 Werte von 10 für Launch/Business bzw. 50 für Enterprise, 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. Das Messaging-Konversationslimit gilt ebenfalls. send_dm erfordert das Messaging-Add-on auf dem Profil, und jede damit gesendete DM zählt zum monatlichen Konversationslimit dieses Profils, genauso wie eine DM, die Sie selbst senden. Wenn das Limit erreicht ist, wird ein send_dm an einen neuen Empfänger nicht gesendet, und die Activity-Zeile erhält den Status failed, mit der Limit-Meldung in actionResults[].errorDetails. Durch einen Kommentar ausgelöste DMs (comment_keyword und story_comment) sind die Ausnahme: Sie werden auch beim Erreichen des Limits gesendet und weiterhin gezählt. 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 Meta 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- oder Facebook-Seiten-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 vom eigenen Konto der Automatisierung – am häufigsten ein Kommentar zu einem eigenen Beitrag. Im letzten Fall wird keine Aktion ausgeführt: keine DM (ein Konto kann sich nicht selbst anschreiben) und auch kein `fire_webhook` oder `send_email`. Eine Automatisierung, die `automation.completed` aktiviert hat, erhält dieses Ereignis weiterhin, mit diesem Status

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. Eine send_dm-Aktion wird in dem Moment als sent markiert, in dem Meta die Nachricht akzeptiert – egal ob sie von Ihrem Instagram-Konto oder über Messenger von Ihrer Facebook-Seite gesendet wird. Die Automatisierung erfasst nur diese Annahme; die Zustellung verfolgt sie nicht. Instagram legt die Nachrichtenzustellung auf keiner API offen, und 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`

Launch-Pläne sind eingeschlossen. Business Launch wird der Business-Stufe zugeordnet, daher stehen Automatisierungen in den Plänen Launch, Business und Enterprise zur Verfügung. 468 wird nur an Pläne zurückgegeben, die keine Automatisierungen enthalten.

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 Meta die Nachricht akzeptiert hat, nicht dass sie zugestellt wurde. Das gilt auf Instagram und auf Facebook (Messenger von Ihrer Seite): Die Automatisierung erfasst nur die Annahme und verfolgt die Zustellung nicht. Auf Instagram hängt die Zustellung 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- oder Facebook-Seiten-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 Versand wird 20–60 Sekunden nach dem Engagement geplant, damit DMs für die Anti-Spam-Systeme von Instagram organisch wirken. Die Verzögerung wird auf das Engagement angewendet, bevor eine Regel abgeglichen wird, und gilt daher für jede Aktion der Regel, einschließlich fire_webhook und send_email – Ihr Webhook trifft 20–60 Sekunden nach dem Kommentar ein, nicht sofort. 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

Übersicht der Automations-API

Funktionsweise

Trigger

Evergreen-Regeln mit `"all"`

Facebook-Seiten

Aktionen

Dedup-Fenster pro Aktion

Dynamischer Nachrichteninhalt

Webhook-Ereignisse

`automation.triggered`

`automation.completed`

Wenn kein Webhook registriert ist

Template-Variablen

Ratenlimits und Obergrenzen

Activity-Status

Fehlercodes

Was Meta NICHT erlaubt

Nutzung mit mehreren Profilen

FAQ

Endpunkte

​Funktionsweise

​Trigger

​Evergreen-Regeln mit "all"

​Facebook-Seiten

​Aktionen

​Dedup-Fenster pro Aktion

​Dynamischer Nachrichteninhalt

​Webhook-Ereignisse

​automation.triggered

​automation.completed

​Wenn kein Webhook registriert ist

​Template-Variablen

​Ratenlimits und Obergrenzen

​Activity-Status

​Fehlercodes

​Was Meta NICHT erlaubt

​Nutzung mit mehreren Profilen

​FAQ

​Endpunkte

Funktionsweise

Trigger

Evergreen-Regeln mit `"all"`

Facebook-Seiten

Aktionen

Dedup-Fenster pro Aktion

Dynamischer Nachrichteninhalt

Webhook-Ereignisse

`automation.triggered`

`automation.completed`

Wenn kein Webhook registriert ist

Template-Variablen

Ratenlimits und Obergrenzen

Activity-Status

Fehlercodes

Was Meta NICHT erlaubt

Nutzung mit mehreren Profilen

FAQ

Endpunkte