{{recipient_username}} engaged with: {{comment_text}}
" } ``` ```json Action with per-action dedup override theme={"system"} { "type": "send_dm", "message": "Thanks {{recipient_username}}!", "dedupWindowMinutes": 1440 // 24h instead of the 7-day default } ``` > [!NOTE] > > **Platform compatibility.** Each trigger and action declares which platforms it supports. The validator rejects the request when an entry's `type` is not supported on the requested `platform`. All triggers support Instagram; `comment_keyword`, `dm_keyword` and `dm_reaction` also support Facebook. `send_dm` supports both, `fire_webhook` and `send_email` are platform-agnostic. ```bash cURL theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "platform": "instagram", "name": "Spring promo", "triggers": [ { "type": "comment_keyword", "postId": "17895695668004550", "keywords": ["INFO", "LINK"] } ], "actions": [ { "type": "send_dm", "message": "Hey {{recipient_username}}, here is the link you wanted: https://example.com" } ] }' \ -X POST https://api.ayrshare.com/api/automations ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; fetch("https://api.ayrshare.com/api/automations", { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ platform: "instagram", name: "Spring promo", triggers: [ { type: "comment_keyword", postId: "17895695668004550", keywords: ["INFO", "LINK"], }, ], actions: [ { type: "send_dm", message: "Hey {{recipient_username}}, here is the link you wanted: https://example.com", }, ], }), }) .then((res) => res.json()) .then((json) => console.log(json)) .catch(console.error); ``` ```python Python theme={"system"} import requests payload = { "platform": "instagram", "name": "Spring promo", "triggers": [ { "type": "comment_keyword", "postId": "17895695668004550", "keywords": ["INFO", "LINK"], } ], "actions": [ { "type": "send_dm", "message": "Hey {{recipient_username}}, here is the link you wanted: https://example.com", } ], } headers = { "Authorization": "Bearer API_KEY", "Content-Type": "application/json", } r = requests.post( "https://api.ayrshare.com/api/automations", json=payload, headers=headers, ) print(r.json()) ``` ```php PHP theme={"system"} $curl = curl_init(); $data = [ "platform" => "instagram", "name" => "Spring promo", "triggers" => [ [ "type" => "comment_keyword", "postId" => "17895695668004550", "keywords" => ["INFO", "LINK"], ], ], "actions" => [ [ "type" => "send_dm", "message" => "Hey {{recipient_username}}, here is the link you wanted: https://example.com", ], ], ]; curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ayrshare.com/api/automations", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => [ "Authorization: Bearer API_KEY", "Content-Type: application/json", ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```json 200: Success theme={"system"} { "status": "success", "id": "auto_9xKp2Lm4nQ" } ``` ```json 400: Validation failed — unknown template variable theme={"system"} { "action": "request", "status": "error", "code": 473, "message": "Validation failed. Please see: https://www.ayrshare.com/docs/introduction", "details": { "formErrors": [], "fieldErrors": { "actions": ["message contains unknown template variables"] } } } ``` ```json 400: Validation failed — comment_keyword trigger missing keywords theme={"system"} { "action": "request", "status": "error", "code": 473, "message": "Validation failed. Please see: https://www.ayrshare.com/docs/introduction", "details": { "formErrors": [], "fieldErrors": { "triggers": ["Invalid input: expected array, received undefined"] } } } ``` ```json 400: Validation failed — unrecognized field (e.g. accountId) theme={"system"} { "action": "request", "status": "error", "code": 473, "message": "Validation failed. Please see: https://www.ayrshare.com/docs/introduction", "details": { "formErrors": ["Unrecognized key: \"accountId\""], "fieldErrors": {} } } ``` ```json 403: Plan tier required theme={"system"} { "action": "automation", "status": "error", "code": 468, "message": "DM automations require a Business or Enterprise plan" } ``` ```json 403: Feature flag not yet enabled theme={"system"} { "action": "request", "status": "error", "code": 472, "message": "This feature is not yet available on your account. Please contact us if you'd like early access." } ``` ```json 400: No linked social account for this platform theme={"system"} { "action": "automation", "status": "error", "code": 471, "message": "No social account linked on the requested platform for this profile. Link the account on the Social Accounts page and try again." } ``` ```json 429: Active automation cap reached theme={"system"} { "action": "automation", "status": "error", "code": 470, "message": "Active automation limit reached for your plan tier" } ``` # Delete Automation Source: https://www.ayrshare.com/docs/apis/automations/delete-automation DELETE /automations/:id Soft-delete an automation by ID to stop new dispatches. Activity history stays queryable, it no longer counts against your cap, and it can't be restored. > [!NOTE] > > **Beta.** See the [Automations Overview](/docs/apis/automations/overview) for the full feature description. Soft-deletes the automation. The master row is flagged `deleted: true, active: false`; no new dispatches occur from this point on. Existing triggers, actions, and activity rows are **not** cascaded. The activity history remains queryable via [`GET /automations/:id/activity`](/docs/apis/automations/get-activity) for as long as the rows exist in Firestore (retention is indefinite for trace and analytics). Soft-deleted automations no longer count against your active automation cap. They cannot be restored via the API; create a new automation instead. ## Header Parameters **Authorization** `string` *required* [API Key](/docs/apis/overview#authorization) of the Primary Profile. Format: `Authorization: Bearer API_KEY` **Profile-Key** `string` [Profile Key](/docs/apis/overview#profile-key-format) of a User Profile. Format: `Profile-Key: PROFILE_KEY` ## Path Parameters **id** `string` *required* The automation ID returned from `POST /automations`. ```bash cURL theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -X DELETE https://api.ayrshare.com/api/automations/auto_9xKp2Lm4nQ ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; const id = "auto_9xKp2Lm4nQ"; fetch(`https://api.ayrshare.com/api/automations/${id}`, { method: "DELETE", headers: { "Authorization": `Bearer ${API_KEY}` }, }) .then((res) => res.json()) .then((json) => console.log(json)) .catch(console.error); ``` ```python Python theme={"system"} import requests headers = {"Authorization": "Bearer API_KEY"} automation_id = "auto_9xKp2Lm4nQ" r = requests.delete( f"https://api.ayrshare.com/api/automations/{automation_id}", headers=headers, ) print(r.json()) ``` ```php PHP theme={"system"} $id = "auto_9xKp2Lm4nQ"; $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ayrshare.com/api/automations/" . $id, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "DELETE", CURLOPT_HTTPHEADER => ["Authorization: Bearer API_KEY"], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```json 200: Success theme={"system"} { "status": "success", "id": "auto_9xKp2Lm4nQ" } ``` ```json 404: Not found theme={"system"} { "action": "automation", "status": "error", "code": 469, "message": "Automation not found" } ``` # Get Automation Activity Source: https://www.ayrshare.com/docs/apis/automations/get-activity GET /automations/:id/activity Retrieve the last 30 days of dispatch attempts for one automation, newest first, with recipient, matched trigger, per-action results, and status values. > [!NOTE] > > **Beta.** See the [Automations Overview](/docs/apis/automations/overview) for the full feature description. Returns every dispatch attempt for one automation, newest first. Each row records the recipient, the matched trigger, every action's result, and any error. Rows from the last **30 days** are returned. Older rows exist in Firestore (retention is indefinite for analytics) but are excluded from this endpoint for performance. ## Activity row status Each row has a top-level `status` plus a per-action `status` inside `actionResults[]`. | Status | When it's recorded | | - | - | | `pending` | Row was just written; the worker hasn't picked it up yet | | `in_flight` | The worker is currently dispatching | | `sent` | At least one action was **accepted** by the platform, and none hit an auth error. For `send_dm` this means Meta accepted the message — **not** that the recipient received it (see the note below) | | `failed` | No action was accepted, and at least one was rejected by the platform or could not run (and none hit an auth error). The reason is on `actionResults[].errorDetails` | | `auth_error` | The account's Instagram or Facebook Page credentials or messaging permissions could not be used — for example an expired or revoked access token, a missing Facebook Page selection, or Messaging not activated for the profile. The DM was not retried. Per-recipient delivery failures are recorded as `failed`, not here | | `rate_limited` | The daily DM cap (tier or per-profile) was hit. No DM was sent | | `deduplicated` | This action already fired to this recipient inside its dedup window (default 7 days, per-action configurable) | | `skipped` | The automation was suppressed before dispatch — it became inactive or was deleted between fan-out and dispatch, it has no actions configured, or the engagement that triggered it came from the automation's own account — most often a comment on your own post. In that last case no action runs: no DM (an account cannot message itself), and no `fire_webhook` or `send_email` either. An automation that opted in to [`automation.completed`](/docs/apis/automations/overview#automation-completed) still receives that event, with this status | `pending` and `in_flight` are transient; everything else is terminal. When an automation has more than one action, the top-level `status` is derived from the per-action results in this order: `auth_error` if any action hit an auth error, then `sent` if any action was accepted, then `deduplicated` if every action was deduplicated, then `skipped` if every action was deliberately suppressed (skipped or deduplicated), otherwise `failed`. Read `actionResults[]` for the per-action detail. > [!NOTE] > > **`sent` confirms Meta accepted the message, not that the recipient received it.** This holds for Instagram DMs and for Messenger DMs from a Facebook Page: the automation records acceptance only and does not track delivery. Instagram exposes no delivery signal on any API surface, and if the recipient's **Message requests** setting blocks strangers, Meta accepts the send and silently drops it. See [Automation DM Sent but Not Delivered](/docs/help-center/technical-support/automation-dm-sent-but-not-delivered). ## Per-action result fields Each entry in `actionResults[]` describes one action's outcome: | Field | Type | Description | | - | - | - | | `actionId` | string | The action's stable ID within the automation | | `type` | string | The action type (`send_dm`, `fire_webhook`, `send_email`) | | `status` | string | Per-action status, using the same vocabulary as the row `status` above | | `errorDetails` | string \| `null` | Human-readable failure reason when the action did not succeed; `null` (or absent) on success. For a rejected `send_dm` this carries the mapped error message (e.g. the private-reply window is closed, or the comment already received a reply). One exception to `null` on success: a `send_dm` with `messageSource: "fallback"` is `sent` and carries the reason its callback was not used. A `fallback` that then failed to send carries the send error followed by that reason | | `messageSource` | string | `send_dm` only. Which text the DM was built from: `template` (the static `message`), `callback` (your [`messageUrl`](/docs/apis/automations/overview#dynamic-message-content) answered and its text was used) or `fallback` (`messageUrl` was set but unusable, so `message` was used instead, with the reason on `errorDetails`). It does not say whether the DM was delivered; `status` does. Present once the DM text has been worked out, including sends that then failed. Absent when the action stopped before that (a `skipped` DM to your own account, a `deduplicated` action, or a `failed` configuration error such as a missing comment id), and for other action types | | `config` | object (optional) | The action's configuration as it was when this fire ran, for example the `send_dm` `message` template. Stays the same if you later edit the automation, so each row shows what was configured at the time. Absent on rows written before this field was added, and when it was removed to fit the size limit (`truncated` is then `true`) | | `sent` | object (optional) | What the action sent, or tried to send, for this fire. Recorded once the action built its message or payload, including when the send then failed: `status` says whether it went out. Absent when the action stopped before sending, for example a `skipped` result for a comment from your own account, and for `deduplicated` results. See [what `sent` contains](#what-sent-contains) | | `truncated` | boolean (optional) | `true` when the entry was cut to fit its size limit: a long text value was shortened, or `config` and then `sent` were left out entirely. Absent otherwise | | `completedAt` | string | ISO 8601 timestamp when the action finished | ### What `sent` contains | Action type | `sent` fields | | - | - | | `send_dm` | `message`: the text the DM was sent with. That is your `message` template with its placeholders filled in for this recipient or, when `messageSource` is `callback`, the text your `messageUrl` returned. `fallbackMessage`: present only when `messageSource` is `callback`; your template, filled in, as it would have been sent without the callback | | `send_email` | `to`, `subject` and `message`: the email as it was queued, placeholders filled in | | `fire_webhook` | `payload`: the event fields sent to your webhook. The delivered body also carries the standard webhook fields (`action`, `created`, `hookId`, `refId`, `url`, and `timeStamp` when the webhook is signed). `hookId`: the delivery's id, present when the webhook was queued | Long text values are cut to 4,000 characters, and `truncated` is set when that happens. Values stored under key names that look like credentials, such as `token`, `secret`, `password` or `apiKey`, are recorded as `"[redacted]"`. A `send_dm` action's `messageUrl` is always recorded as `"[redacted]"` too, because a URL can carry a secret in its path or query string. For comment-triggered automations (`comment_keyword`), the row also carries a top-level `commentId` — the raw Instagram comment ID the DM was anchored to. It is `null` for message-driven triggers (`dm_keyword`, `story_reply`, `dm_reaction`). Rows also carry `postId` (the post a `comment_keyword` comment was left on) and `storyId` (the story for `story_reply` and `story_comment`). Each is `null` for the other triggers, and absent on rows written before these fields were added. ## Header Parameters **Authorization** `string` *required* [API Key](/docs/apis/overview#authorization) of the Primary Profile. Format: `Authorization: Bearer API_KEY` **Profile-Key** `string` [Profile Key](/docs/apis/overview#profile-key-format) of a User Profile. Format: `Profile-Key: PROFILE_KEY` ## Path Parameters **id** `string` *required* The automation ID returned from `POST /automations`. ## Query Parameters **limit** `number` (default: 25) Page size. Default `25`, max `100`. Values outside `[1, 100]` are clamped; non-integer or `≤0` returns HTTP 400. **next** `string` Opaque cursor from a previous response's `meta.pagination.next`. Omit on the first request. Forward-only — passing `?previous=` returns HTTP 400. ## Response Shape The response wraps the result list in `activity[]` and the cursor info in `meta.pagination`: ```json theme={"system"} { "status": "success", "automationId": "auto_9xKp2Lm4nQ", "activity": [ /* …rows, newest first… */ ], "meta": { "pagination": { "hasMore": true, "limit": 25, "next": "eyJ0aW1lIjoiMjAyNi0wNS0xMlQwOTowMDoxMS4wMDBaIiwiaWQiOiJhdXRvXzl4S3AyTG00blE6dHJnX2ExYjJjMzpjb21tZW50X3JlY2VpdmVkOjE4MDEyMzQ1Njc4OTAwMDAwIn0=" } } } ``` `meta.pagination.next` is a base64-encoded opaque blob — treat it as a black box and pass it back unchanged in the next request's `?next=`. `meta.pagination.hasMore` is `true` when at least one more page exists. ```bash cURL — first page theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -X GET "https://api.ayrshare.com/api/automations/auto_9xKp2Lm4nQ/activity?limit=25" ``` ```bash cURL — next page theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -X GET "https://api.ayrshare.com/api/automations/auto_9xKp2Lm4nQ/activity?limit=25&next=eyJ0aW1lIjoiMjAyNi0wNS0xMlQw..." ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; const id = "auto_9xKp2Lm4nQ"; // Paginate through every page let next; do { const url = new URL(`https://api.ayrshare.com/api/automations/${id}/activity`); url.searchParams.set("limit", "25"); if (next) url.searchParams.set("next", next); const res = await fetch(url, { headers: { "Authorization": `Bearer ${API_KEY}` }, }); const json = await res.json(); console.log(json.activity); next = json.meta?.pagination?.hasMore ? json.meta.pagination.next : undefined; } while (next); ``` ```python Python theme={"system"} import requests headers = {"Authorization": "Bearer API_KEY"} automation_id = "auto_9xKp2Lm4nQ" params = {"limit": 25} while True: r = requests.get( f"https://api.ayrshare.com/api/automations/{automation_id}/activity", params=params, headers=headers, ).json() print(r["activity"]) pagination = r.get("meta", {}).get("pagination", {}) if not pagination.get("hasMore"): break params["next"] = pagination["next"] ``` ```php PHP theme={"system"} $id = "auto_9xKp2Lm4nQ"; $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ayrshare.com/api/automations/" . $id . "/activity?limit=25", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => ["Authorization: Bearer API_KEY"], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```json 200: Success theme={"system"} { "status": "success", "automationId": "auto_9xKp2Lm4nQ", "activity": [ { "id": "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:18012345678901234", "automationId": "auto_9xKp2Lm4nQ", "triggerId": "trg_a1b2c3", "triggerType": "comment_keyword", "recipientId": "17841401234567890", "recipientUsername": "jane_doe", "eventId": "comment.received:18012345678901234", "commentId": "18012345678901234", "platform": "instagram", "status": "sent", "actionResults": [ { "actionId": "act_d4e5f6", "type": "send_dm", "status": "sent", "errorDetails": null, "messageSource": "template", "config": { "message": "Hi {{recipient_username}}, here's the link: https://example.com" }, "sent": { "message": "Hi jane_doe, here's the link: https://example.com" }, "completedAt": "2026-05-12T09:14:48.000Z" } ], "keyword": "LINK", "commentText": "Send me the LINK please!", "created": "2026-05-12T09:14:22.000Z", "completedAt": "2026-05-12T09:14:48.000Z" }, { "id": "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:18012345678905555", "automationId": "auto_9xKp2Lm4nQ", "triggerId": "trg_a1b2c3", "triggerType": "comment_keyword", "recipientId": "17841405555555555", "recipientUsername": "late_commenter", "eventId": "comment.received:18012345678905555", "commentId": "18012345678905555", "platform": "instagram", "status": "failed", "actionResults": [ { "actionId": "act_d4e5f6", "type": "send_dm", "status": "failed", "errorDetails": "Cannot send private reply: This comment is no longer eligible for a private reply.", "completedAt": "2026-05-12T09:12:03.000Z" } ], "keyword": "LINK", "commentText": "LINK please!", "created": "2026-05-12T09:12:01.000Z", "completedAt": "2026-05-12T09:12:03.000Z" }, { "id": "auto_9xKp2Lm4nQ:trg_a1b2c3:comment.received:18012345678900000", "automationId": "auto_9xKp2Lm4nQ", "triggerId": "trg_a1b2c3", "triggerType": "comment_keyword", "recipientId": "17841409876543210", "recipientUsername": "repeat_user", "eventId": "comment.received:18012345678900000", "commentId": "18012345678900000", "platform": "instagram", "status": "deduplicated", "actionResults": [], "keyword": "LINK", "commentText": "LINK again please", "created": "2026-05-12T09:00:11.000Z", "completedAt": "2026-05-12T09:00:34.000Z" } ], "meta": { "pagination": { "hasMore": true, "limit": 25, "next": "eyJ0aW1lIjoiMjAyNi0wNS0xMlQwOTowMDoxMS4wMDBaIiwiaWQiOiJhdXRvXzl4S3AyTG00blE6dHJnX2ExYjJjMzoxODAxMjM0NTY3ODkwMDAwMCJ9" } } } ``` ```json 400: Bad limit theme={"system"} { "status": "error", "message": "limit must be a positive integer" } ``` ```json 400: Backward pagination not supported theme={"system"} { "status": "error", "message": "'previous' pagination is not supported by this endpoint" } ``` ```json 404: Not found theme={"system"} { "action": "automation", "status": "error", "code": 469, "message": "Automation not found" } ``` # Get Automation Source: https://www.ayrshare.com/docs/apis/automations/get-automation GET /automations/:id Fetch one automation by ID, including every attached trigger and action, its active status, and stats such as totalSent and lastTriggeredAt. > [!NOTE] > > **Beta.** See the [Automations Overview](/docs/apis/automations/overview) for the full feature description. Returns one automation including every attached trigger and action. Soft-deleted automations return `469` so an attacker probing for IDs gets the same response as a legitimate "not found". ## Header Parameters **Authorization** `string` *required* [API Key](/docs/apis/overview#authorization) of the Primary Profile. Format: `Authorization: Bearer API_KEY` **Profile-Key** `string` [Profile Key](/docs/apis/overview#profile-key-format) of a User Profile. Format: `Profile-Key: PROFILE_KEY` ## Path Parameters **id** `string` *required* The automation ID returned from `POST /automations`. ```bash cURL theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -X GET https://api.ayrshare.com/api/automations/auto_9xKp2Lm4nQ ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; const id = "auto_9xKp2Lm4nQ"; fetch(`https://api.ayrshare.com/api/automations/${id}`, { method: "GET", headers: { "Authorization": `Bearer ${API_KEY}` }, }) .then((res) => res.json()) .then((json) => console.log(json)) .catch(console.error); ``` ```python Python theme={"system"} import requests headers = {"Authorization": "Bearer API_KEY"} automation_id = "auto_9xKp2Lm4nQ" r = requests.get( f"https://api.ayrshare.com/api/automations/{automation_id}", headers=headers, ) print(r.json()) ``` ```php PHP theme={"system"} $id = "auto_9xKp2Lm4nQ"; $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ayrshare.com/api/automations/" . $id, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => ["Authorization: Bearer API_KEY"], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```json 200: Success theme={"system"} { "status": "success", "id": "auto_9xKp2Lm4nQ", "platform": "instagram", "accountId": "17841400000000000", "name": "Spring promo", "description": "", "active": true, "stats": { "totalSent": 42, "totalFailed": 1, "lastTriggeredAt": "2026-05-12T09:14:22.000Z", "lastSentAt": "2026-05-12T09:14:48.000Z" }, "created": "2026-04-30T12:00:00.000Z", "updated": "2026-05-12T09:14:48.000Z", "triggers": [ { "id": "trg_a1b2c3", "type": "comment_keyword", "active": true, "config": { "postId": "17895695668004550", "keywords": ["INFO", "LINK"] } } ], "actions": [ { "id": "act_d4e5f6", "type": "send_dm", "active": true, "config": { "message": "Hey {{recipient_username}}, here is the link you wanted: https://example.com" } } ] } ``` ```json 404: Not found theme={"system"} { "action": "automation", "status": "error", "code": 469, "message": "Automation not found" } ``` # List Automations Source: https://www.ayrshare.com/docs/apis/automations/list-automations GET /automations Returns every active and inactive automation for the caller, excluding soft-deleted ones, with an optional platform filter for instagram or facebook. > [!NOTE] > > **Beta.** See the [Automations Overview](/docs/apis/automations/overview) for the full feature description. Returns every active and inactive automation for the caller. Soft-deleted automations are excluded. ## Header Parameters **Authorization** `string` *required* [API Key](/docs/apis/overview#authorization) of the Primary Profile. Format: `Authorization: Bearer API_KEY` **Profile-Key** `string` [Profile Key](/docs/apis/overview#profile-key-format) of a User Profile. Format: `Profile-Key: PROFILE_KEY` ## Query Parameters **platform** `string` Optional. Filter to automations targeting this platform: `instagram` or `facebook`. ```bash cURL theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -X GET "https://api.ayrshare.com/api/automations?platform=instagram" ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; fetch("https://api.ayrshare.com/api/automations?platform=instagram", { method: "GET", headers: { "Authorization": `Bearer ${API_KEY}` }, }) .then((res) => res.json()) .then((json) => console.log(json)) .catch(console.error); ``` ```python Python theme={"system"} import requests headers = {"Authorization": "Bearer API_KEY"} r = requests.get( "https://api.ayrshare.com/api/automations", params={"platform": "instagram"}, headers=headers, ) print(r.json()) ``` ```php PHP theme={"system"} $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ayrshare.com/api/automations?platform=instagram", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => ["Authorization: Bearer API_KEY"], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```json 200: Success theme={"system"} { "status": "success", "automations": [ { "id": "auto_9xKp2Lm4nQ", "platform": "instagram", "accountId": "17841400000000000", "name": "Spring promo", "description": "", "active": true, "stats": { "totalSent": 42, "totalFailed": 1, "lastTriggeredAt": "2026-05-12T09:14:22.000Z", "lastSentAt": "2026-05-12T09:14:48.000Z" }, "created": "2026-04-30T12:00:00.000Z", "updated": "2026-05-12T09:14:48.000Z" } ] } ``` ```json 403: Plan tier theme={"system"} { "action": "automation", "status": "error", "code": 468, "message": "DM automations require a Business or Enterprise plan" } ``` # Automations API Overview Source: https://www.ayrshare.com/docs/apis/automations/overview Build Instagram and Facebook Page rules that send a DM, fire a webhook, or send an email on a comment, a DM or a DM reaction, or an Instagram story reply. > [!NOTE] > > **Beta.** The Automations API is in beta and we are actively collecting feedback. Endpoints, payloads, and limits may change as we iterate. Please send feedback and bug reports to support so we can prioritize the right improvements. The Automations endpoints let you define rules that automatically react to incoming Instagram engagement and to Facebook Page comments and DMs. Each automation pairs one or more **triggers** (the event that fires the rule) with one or more **actions** (what happens when it fires). A single rule can listen for multiple triggers and dispatch multiple actions — fire a webhook into your analytics pipeline AND send a DM from the same engagement. The engine only reacts to engagement a user directs at you (a comment, story reply, DM, or reaction) — it never sends follow-triggered DMs, first-message DMs to strangers, or bulk outbound — and it inherits Ayrshare's per-account rate limits, per-recipient deduplication, and idempotent webhook ingestion. > [!NOTE] > > **`sent` means Meta accepted the message, not that the recipient received it.** On Instagram, delivery is ultimately dictated by the recipient's **Message requests** setting: if they don't allow message requests from everyone, Meta returns a success response and silently drops the message, and this is invisible at every API layer. Even a delivered comment-triggered DM arrives as a **message request the recipient must accept** (unless a conversation already exists between the two accounts). See [Automation DM Sent but Not Delivered](/docs/help-center/technical-support/automation-dm-sent-but-not-delivered) for the full explanation. ## How it works **1. Create an automation** `POST /automations` with the triggers and actions you want. The automation activates immediately. **2. An end user engages** Someone comments on your post, replies to your story, sends a DM, or reacts to a DM. Meta delivers the webhook to Ayrshare. **3. Ayrshare matches and dispatches** A 20–60 second jitter is applied to the engagement to stay inside Instagram's anti-spam heuristics. The engine then looks up every rule matching the event, checks per-action deduplication and your daily DM cap, and runs each action. **4. Inspect what fired** `GET /automations/:id/activity` returns the audit log — every dispatch attempt, the per-action results, and any errors. ## Triggers You can attach up to **50 triggers** to one automation. Each trigger is a discriminated union on the `type` field; type-specific fields live at the same level. The **Platforms** column shows where each trigger is available; see [Facebook Pages](#facebook-pages) for what Facebook needs. | Type | Fires when | Platforms | Config | | - | - | - | - | | `comment_keyword` | A comment matching a keyword lands on a post or reel | `instagram`, `facebook` | `postId` (required — a post ID, or `"all"`); `keywords` (required, ≥1 entry) | | `story_reply` | A user replies to a story via DM | `instagram` | `storyId` (optional — a story ID, or `"all"`) | | `dm_reaction` | A user reacts to one of your DMs with an emoji | `instagram`, `facebook` | `emoji` (optional — omit to fire on any emoji) | | `dm_keyword` | A user sends a DM whose text matches a keyword | `instagram`, `facebook` | `keywords` (required, ≥1 entry) | Keyword matching is **case-insensitive** and whole-word. An event satisfies a keyword-filtered trigger if it contains any one of the configured keywords. ### Evergreen rules with `"all"` Set `postId` (or `storyId`) to the literal lowercase string `"all"` to fire on **every** post, reel, or story on the connected account instead of one specific piece of content. This is what you want for a rule that should keep working as new content is published, with no API call per post: ```json theme={"system"} { "type": "comment_keyword", "postId": "all", "keywords": ["LINK", "INFO"] } ``` The value must be exactly `"all"`. A variant such as `"ALL"` or `" all"` is rejected with a validation error rather than saved as a post ID that would never match. `"all"` never widens beyond the connected account — a rule on one profile cannot fire on another profile's content. Your daily DM cap and the engagement-anchored send rules apply exactly as they do to a single-post rule. > [!WARNING] > > Deduplication is counted per automation and recipient, not per post. On an `"all"` rule, a user who comments a keyword on two different posts within the dedup window (7 days by default) receives the DM only once; the second activity is recorded as `deduplicated`. A smaller [`dedupWindowMinutes`](#per-action-dedup-window) only shortens that window; it does not make deduplication per post. Setting it to `0` turns deduplication off, so every matching comment sends a DM, including repeat comments on the same post. > [!NOTE] > > On the story triggers, omitting `storyId` behaves the same as `"all"`. Prefer `"all"` — it states the intent explicitly, and omission will be retired in a future release with advance notice on [Upcoming API Changes](/docs/whatsnew/upcoming-api-changes). ### Facebook Pages Set `platform` to `facebook` to run an automation on the Facebook Page linked to the profile. DMs are sent from the Page through Messenger. * **Triggers:** `comment_keyword`, `dm_keyword` and `dm_reaction`. Story triggers are Instagram-only, and a Facebook automation that uses one is rejected with a validation error. * **Messaging:** the profile needs [Messaging](/docs/apis/messages/overview) activated for Facebook, the same as sending a Facebook DM with the Messages API. Comments on the Page reach automations only while Messaging is active. * **Recipient:** `{{recipient_username}}` is empty, because Facebook webhooks do not include a username. On DM triggers `{{recipient_id}}` is the user's Page-scoped ID (PSID). ```json theme={"system"} { "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" }] } ``` #### Comments on Facebook Page posts A `comment_keyword` automation on `facebook` fires when someone comments on one of the Page's posts with a matching keyword. `send_dm` then answers with a **private reply**: a Messenger message to the commenter, linked to their comment. The commenter does not need to have messaged the Page first. * **`postId`:** the Facebook post ID that `/post` returns in `postIds[].id` (for example `104923907983682_108329000309742`), or `"all"` for every post on the Page. * **Replies count:** a reply to another comment fires the rule too, on the post it belongs to. * **What does not fire:** comments the Page itself writes (including comments and `firstComment` sent through Ayrshare), and edited, hidden or deleted comments. * **One reply per comment:** Meta accepts one private reply per comment, within 7 days of the comment. When Meta refuses one, the activity fails with a code from the [private-reply error range](/docs/errors/errors-ayrshare#automation-private-reply-comment-dm-errors). * **Page admins get no reply:** Meta does not send a private reply to a comment written by an admin of the Page. The rule still fires, and the activity fails with Meta's reason on `errorDetails`: `Cannot Reply to Activity: This user cant reply to this activity`. To test the automation, comment from an account that does not manage the Page. ```json theme={"system"} { "platform": "facebook", "name": "Send the link on request", "triggers": [{ "type": "comment_keyword", "postId": "all", "keywords": ["LINK"] }], "actions": [{ "type": "send_dm", "message": "Thanks for commenting! Here is the link: https://example.com" }] } ``` ## Actions You can attach up to **50 actions** to one automation. They run sequentially; each result is recorded on the activity row. | Type | Effect | Config | | - | - | - | | `send_dm` | Sends a DM (Instagram, or Messenger from your Facebook Page) to the user who triggered the rule, using a [templated message](#template-variables) or [text you generate per fire](#dynamic-message-content). | `message` (required, templated); `messageUrl` (optional); `timeoutMs` (optional) | | `fire_webhook` | POSTs the automation context to your account-level webhook URL (configure via [`POST /hook/webhook`](/docs/apis/webhooks/register)). | `sendCompletedEvent` (optional, boolean — also send [`automation.completed`](#automation-completed)). Payload shape is fixed; see [below](#fire_webhook-payload) | | `send_email` | Queues an email via the platform's mail pipeline. | `to` (required, email); `subject` (optional, templated); `message` (required, templated) | ### Per-action dedup window Every action — regardless of type — additionally accepts an optional top-level `dedupWindowMinutes` field that overrides the **default 7-day** per-recipient dedup window for that action only. * Set to `0` to **disable** dedup entirely for that action (typical for `fire_webhook` / `send_email` where the receiver expects every event). * Capped at `525600` (one year). ```json Action with a 24h dedup override theme={"system"} { "type": "send_dm", "message": "Thanks {{recipient_username}}!", "dedupWindowMinutes": 1440 } ``` ### Dynamic message content By default, `send_dm` sends the same `message` to everyone who triggers the rule. Placeholders such as `{{recipient_username}}` are the only part that changes from person to person. Set **`messageUrl`** on the action and your own server writes the DM for each person instead: every time the rule matches, we ask your endpoint what to say, then send its answer as the DM. **Example.** Your rule replies to anyone who comments "LINK" on a post, and `messageUrl` points at your server. When Ava comments "LINK please!": 1. We `POST` the details to your `messageUrl`: who commented (`"recipientUsername": "ava"`), what they wrote, and which post it was on. 2. Your server writes a reply for Ava, for example with a tracking link made just for her, and answers `{ "message": "Hi ava, here's your link: https://example.com/r/12345" }`. 3. We send that text to Ava as the DM, exactly as you wrote it. If your server does not answer within `timeoutMs`, returns an error, or returns something we cannot use, we send Ava the action's regular `message` instead, so she still gets a reply. Add it to a `send_dm` action like this: ```json send_dm with messageUrl theme={"system"} { "type": "send_dm", "messageUrl": "https://yourapp.example.com/automations/message", "timeoutMs": 3000, "message": "Thanks for commenting! Here is the link: https://example.com" } ``` `messageUrl` is where we ask for the text. `message` is still required and is the fallback: it is never sent to your server, and we DM it instead whenever your server does not answer in time, returns an error, or returns something we cannot use (see the warning below). `timeoutMs` is optional (default 3000, maximum 5000). **What we send your endpoint.** A `POST` with this JSON body: ```json Callback request body theme={"system"} { "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 } ``` | Field | Meaning | | - | - | | `automationId`, `triggerId`, `trigger`, `platform` | Which automation and trigger fired, as on the [`fire_webhook` payload](#fire_webhook-payload) | | `recipientId`, `recipientUsername` | The person the DM goes to. `recipientUsername` is `null` when the trigger does not carry one (for example `dm_keyword`) | | `keyword` | The keyword that matched, or `null` | | `activityId` | The activity entry for this fire, so you can match it to [`GET /automations/:id/activity`](/docs/apis/automations/get-activity) | | `actionId` | Which `send_dm` action is asking, matching `actionResults[].actionId`. Lets one endpoint serve several `send_dm` actions on the same automation | | `eventId` | Our id for the engagement that caused the fire | | `commentId` | The Instagram comment id for comment triggers; `null` for DM and story triggers | | `commentText` | The text that matched: the comment, the DM, or the reaction emoji. `null` when there is none (for example `story_reply`) | | `postId`, `storyId` | The post or story the engagement landed on, or `null` | | `timestamp` | When we made the request, ISO 8601 | | `timeStamp` | The same moment as a Unix time **in seconds**. Present only when the callback is signed, as on our webhooks | If you have registered a [webhook secret](/docs/apis/webhooks/register), the body is signed with the same secret as your `automations` webhooks, in the same way: `X-Authorization-Content-SHA256` is the HMAC-SHA256 of the raw body, and `X-Authorization-Timestamp` carries the body's `timeStamp`. The verification code you already use for our webhooks works unchanged. If a secret is registered but we cannot read it at that moment, we do **not** send the callback unsigned; we send your `message` template instead. **Where it can point.** `messageUrl` must be a public HTTPS address. A URL that resolves to a private, loopback, link-local or cloud-metadata address is refused, and redirects are not followed — a `3xx` answer counts as a failure. Either way the template is sent instead. **What your endpoint sends back.** Return `200` with a JSON body, at most 16 KB, containing a `message` string of 1 to 1000 characters: ```json theme={"system"} { "message": "Hi ava — grabbed that link for you: https://example.com/r/12345" } ``` Your text is sent **verbatim**. `{{placeholder}}` substitution is not applied to it, so a literal `{{` in your generated text reaches the recipient as written. > [!WARNING] > > **`message` stays required, and it is not decoration.** If your endpoint times out, returns a non-2xx, returns a body we cannot use, or has been temporarily circuit-broken after repeated failures, we send the rendered `message` template instead. That send can still fail, for example if the template renders empty (see below) or Instagram rejects it. We never retry the callback — a retry risks sending the recipient two messages. `timeoutMs` defaults to **3000**. The maximum is **5000**: a larger value is rejected with a validation error when you create or update the automation. It covers the whole exchange, including reading your response body. Budget for it: the DM is sent after your endpoint answers, so a slow endpoint delays the message. Check which path a fire took on [`GET /automations/:id/activity`](/docs/apis/automations/get-activity). A `send_dm` entry in `actionResults[]` carries `messageSource` once the DM text has been worked out, including when the send then failed. It is absent when the action stopped before that, for example a `skipped` DM to your own account or a `deduplicated` action: | `messageSource` | Meaning | | - | - | | `template` | No `messageUrl` configured; the static `message` was used | | `callback` | Your endpoint answered and its text was used | | `fallback` | `messageUrl` was set but unusable; `message` was used instead | `messageSource` says which text the DM was built from, not whether it was delivered. Read the entry's `status` for that. A fallback on its own does not fail the action: when the template DM is delivered, the entry is `sent`, with the reason the callback was not used on `errorDetails`. If the template DM then fails too, the entry is `failed` and `errorDetails` gives the send error followed by the callback reason. Watch for it: a callback failing on every fire otherwise looks exactly like one that is working. Keep your `message` sendable on its own. If it renders empty for a recipient, for example `{{recipient_username}}` alone on a DM trigger that carries no username, and your callback text is not used, no DM is sent and the action is `failed` with the reason on `errorDetails`. ### Webhook events Two events are delivered to the `automations` webhook action you register with [`POST /hook/webhook`](/docs/apis/webhooks/register). Both carry a **`type`** field — switch on it before reading anything else. | `type` | Sent when | | - | - | | `automation.triggered` | The rule's `fire_webhook` action runs | | `automation.completed` | The dispatch finished, with its outcome | > [!NOTE] > > `automation.completed` is off by default. Turn it on for an automation by setting `"sendCompletedEvent": true` on its `fire_webhook` action. It stays off otherwise, so a receiver built for one payload per fire keeps getting exactly one. `automation.triggered` is not a record of every match: it is sent only when `fire_webhook` itself runs, so a match that ends `rate_limited` or `deduplicated` produces `automation.completed` alone. Neither event is sent for an automation that was deactivated or deleted before the dispatch ran. #### `automation.triggered` ```json theme={"system"} { "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` is the row `GET /automations/:id/activity` returns, so you can join the two exactly rather than matching on `recipientId` + `triggerId` + `keyword` — which is ambiguous when several people comment the same keyword at once. `actionId` is the `fire_webhook` action that sent the event, and matches `actionResults[].actionId`; it tells two `fire_webhook` actions on the same rule apart. Fields a trigger doesn't populate are `null` rather than omitted, so the shape is stable. `recipientUsername` is `null` for `dm_keyword`, `dm_reaction` and `story_reply`, and for every Facebook trigger, because Meta's payload doesn't include one. `commentId` is set only for `comment_keyword` and `story_comment`, `postId` only for `comment_keyword`, and `storyId` only for the story triggers. `story_reply` has no `keyword`. For `dm_keyword`, `commentText` is the DM text; for `dm_reaction`, `commentText` and `keyword` are both the reaction emoji. #### `automation.completed` Sent only when the automation opts in on its `fire_webhook` action: ```json fire_webhook action with the outcome event on theme={"system"} { "type": "fire_webhook", "sendCompletedEvent": true } ``` ```json theme={"system"} { "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` and each `actionResults[].status` use the same values as the [activity log](#activity-statuses) — `sent`, `failed`, `rate_limited`, `deduplicated`, `skipped`, `auth_error` — so in the normal case you learn how a dispatch ended without polling. Delivery of this event is best-effort, though: if the process stops between recording the outcome and queuing the event, it is not sent. The activity log is the record of truth, so if you need every outcome, reconcile against `GET /automations/:id/activity` for any `activityId` that has not reported one. A `send_dm` result also carries `messageSource`, as on the [activity log](#dynamic-message-content): `template`, `callback` or `fallback`, so you can spot a `messageUrl` that keeps falling back without polling. Match results to your configured actions by `actionId`, not by position — two actions of the same type are only distinguishable that way. `actionResults` is empty in three cases, each with the reason on the top-level `errorDetails` where there is one: `rate_limited` (your daily cap was reached), `deduplicated` (every action was inside its dedup window), and `failed` after the dispatch was retried the maximum number of times without finishing. In that last case some actions may already have run, so a DM may have gone out and `automation.triggered` may already have been sent. Webhook delivery is at-least-once, so the same event can occasionally arrive twice, and a dispatch that is retried can send `automation.triggered` again with a new `hookId`. Never deduplicate on `hookId`. Key each event type separately, so that processing one never suppresses the other: `automation.completed` on `activityId` (each activity has one outcome), and `automation.triggered` on `activityId` plus `actionId` (one per `fire_webhook` action). The two events are delivered independently, so `automation.completed` can occasionally arrive before `automation.triggered`. #### If no webhook is registered `fire_webhook` posts to the `automations` action registered on the profile, falling back to your Primary Profile. There is **no** fallback to another action such as `messages`. If neither registration exists, `automation.triggered` is not silently dropped: the action is recorded on the activity row as `failed`, with the reason in `actionResults[].errorDetails`. (`automation.completed` has nowhere to go either, and is not recorded.) The dispatch's overall status then follows the usual precedence: `auth_error` if any action hit an auth error, otherwise `sent` if any action was accepted, otherwise `failed`. So the missing webhook counts toward the automation's failure stats only when nothing else on the rule sent; when another action did send (and none hit an auth error), the dispatch ends `sent` and the failed webhook shows only in `actionResults[]`. A `fire_webhook` result of `sent` means the event was queued for delivery to your URL, not that your endpoint accepted it. Delivery is then retried on its own schedule. ## Template variables `send_dm.message`, `send_email.subject`, and `send_email.message` support `{{placeholder}}` substitution. **Unknown placeholders are rejected at create/update time** (as a `473` validation error) so a typo never silently leaks the literal `{{foo}}` into a customer-facing message. | Placeholder | Resolves to | | - | - | | `{{recipient_username}}` | The engaging user's Instagram handle, on comment triggers. Empty on DM and story-reply triggers, and always on Facebook | | `{{recipient_id}}` | The engaging user's ID: the Instagram-scoped ID (IGSID) on Instagram, the Page-scoped ID (PSID) on Facebook | | `{{recipient_name}}` | Reserved; resolves to empty until a future enrichment source populates it | | `{{sender_username}}` | Reserved; resolves to empty on every platform for now | | `{{sender_name}}` | Reserved; resolves to empty on every platform for now | | `{{comment_text}}` | The text of the comment / DM / story reply that fired the trigger | | `{{comment_id}}` | The platform id of the comment / message that fired | | `{{comment_sent_at}}` | ISO 8601 timestamp of the event (when available) | | `{{matched_keyword}}` | The keyword that matched (or the emoji string for `dm_reaction`) | | `{{platform}}` | Platform identifier: `instagram` or `facebook` | | `{{trigger_type}}` | Trigger type (e.g. `comment_keyword`) | > [!NOTE] > > **No `sender_email` / `recipient_email`.** These are deliberately not exposed — your billing email has no legitimate place in a DM to a stranger, and Meta does not provide the recipient's email on any IG webhook. Avoiding the placeholders prevents accidental disclosure. Example template: ``` Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com ``` ## Rate limits and caps | Plan | Active automations (per profile) | Daily DM cap (per account) | | - | - | - | | Launch & Business | 10 | 1,000 | | Enterprise | 50 | 5,000 | The active-automation cap is counted **per [User Profile](/docs/apis/profiles/overview)**, not per parent account. Each profile under your account gets its own Launch/Business 10 or Enterprise 50, so an account with many profiles can run that many automations on each. It counts active automations and is enforced on both `POST` (create) and `PUT` re-activation (`active: false → true`), each surfacing error code `470`. Need a higher per-profile limit? [Contact support](mailto:support@ayrshare.com) to have it raised for your account. The **daily DM cap** applies per parent Ayrshare account, shared across all your profiles, with a per-profile sub-cap so one busy profile cannot drain the whole account's quota. When a DM cap is hit, the activity row records status `rate_limited` and no DM is sent. The **messaging conversation limit** also applies. `send_dm` needs the Messaging add-on on the profile, and each DM it sends counts toward that profile's monthly [conversation limit](/docs/apis/messages/overview#conversation-limit-&-pricing), the same as a DM you send yourself. When the limit is reached, a `send_dm` to a new recipient is not sent and the activity row records status `failed`, with the limit message in `actionResults[].errorDetails`. DMs triggered by a comment (`comment_keyword` and `story_comment`) are the exception: they are still sent at the limit, and still counted. Structural caps on a single automation: **1–50 triggers**, **1–50 actions**. Instagram itself caps DMs at roughly 200/hour per account. The engine paces dispatch with a 20–60 second jitter to stay safely under this. ## Activity statuses A row in `GET /automations/:id/activity` carries a top-level `status` plus a per-action `status` inside `actionResults[]`: | Status | Meaning | | - | - | | `pending` | Just written; the worker hasn't picked it up yet | | `in_flight` | Worker is currently dispatching | | `sent` | At least one action was **accepted** by the platform, and none hit an auth error. For `send_dm` this means Meta accepted the message — **not** that the recipient received it (see the note below) | | `failed` | No action was accepted, and at least one was rejected by the platform or could not run (and none hit an auth error). The reason is on `actionResults[].errorDetails` | | `auth_error` | The account's Instagram or Facebook Page credentials or messaging permissions could not be used — for example an expired or revoked access token, a missing Facebook Page selection, or Messaging not activated for the profile. The DM was not retried. Per-recipient delivery failures are recorded as `failed`, not here | | `rate_limited` | The daily DM cap (tier or per-profile) was hit; no DM was sent | | `deduplicated` | This action already fired to this recipient inside its dedup window | | `skipped` | The automation was suppressed before dispatch — it became inactive or was deleted between fan-out and dispatch, it has no actions configured, or the engagement that triggered it came from the automation's own account — most often a comment on your own post. In that last case no action runs: no DM (an account cannot message itself), and no `fire_webhook` or `send_email` either. An automation that opted in to [`automation.completed`](/docs/apis/automations/overview#automation-completed) still receives that event, with this status | `pending` and `in_flight` are transient; everything else is terminal. When an automation has more than one action, the top-level `status` is derived from the per-action results in this order: `auth_error` if any action hit an auth error, then `sent` if any action was accepted, then `deduplicated` if every action was deduplicated, then `skipped` if every action was deliberately suppressed (skipped or deduplicated), otherwise `failed`. Read `actionResults[]` for the per-action detail. > [!NOTE] > > **`sent` is a platform-acceptance receipt, not a delivery receipt.** A `send_dm` action is marked `sent` the moment Meta accepts the message, whether it is sent from your Instagram account or through Messenger from your Facebook Page. The automation records that acceptance only; it does not track delivery. Instagram does not expose message delivery to any API, and whether the recipient actually receives it depends on their Instagram **Message requests** setting, which Ayrshare cannot read or influence. See [Automation DM Sent but Not Delivered](/docs/help-center/technical-support/automation-dm-sent-but-not-delivered). ## Error codes The API returns two shapes of error: * **Business-rule errors** carry a numbered automation `code` (e.g. `{ "action": "automation", "code": 469, ... }`). * **Validation errors** — any malformed request body (missing or invalid fields, unknown template variables, unrecognized keys) — are returned as a single **`473`** response with a `details` object that lists the offending fields. `details` is the validator's output (`formErrors` plus `fieldErrors`). Branch on `details`, not on a per-condition code. In `fieldErrors`, keys are the top-level request fields (`triggers`, `actions`): a problem inside a specific entry, such as a trigger missing its `keywords`, is reported under that field (e.g. `triggers`), while `formErrors` holds object-level issues such as unrecognized keys. | Code | HTTP | Meaning | | - | - | - | | 468 | 403 | Business or Enterprise plan required | | 469 | 404 | Automation not found (also returned when the caller doesn't own it) | | 470 | 429 | Active automation cap reached for your plan tier | | 471 | 400 | No social account linked on the requested platform for this profile | | 472 | 403 | Feature not yet available on your account — contact us for early access | | 473 | 400 | Validation failed (malformed request body) — inspect `details` | > [!NOTE] > > **Launch plans are included.** Business Launch resolves to the Business tier, so Automations > are available on Launch, Business, and Enterprise. `468` is only returned to plans that do > not include Automations. ## What Meta does NOT allow A few commonly-requested capabilities are not supported because Meta doesn't permit them on the public Instagram API: * **Auto-DM on new followers.** Instagram does not publish a follow webhook. * **First-message DMs to strangers.** Meta requires the recipient to have engaged first (comment, reply, DM, reaction) before a business account can message them. Every supported trigger is anchored to such an engagement — but note that being *allowed* to send is not the same as the message being *delivered*: the recipient's Instagram **Message requests** setting can still cause Meta to accept and then silently drop the message (see [Automation DM Sent but Not Delivered](/docs/help-center/technical-support/automation-dm-sent-but-not-delivered)). * **Bulk outbound campaigns.** Hourly DM caps and anti-abuse heuristics apply at the platform level. ## Multi-profile usage The endpoints respect the `profileKey` header. Pass a child profile's key and the automation is created/managed under that profile. Rate limits split across profiles via a per-profile sub-cap so one chatty profile doesn't drain the parent account's quota. ## FAQ > [accordion] Can I trigger on a new follower? > > No. Instagram does not publish a follow webhook, and Meta does not allow third-party apps to send a DM to a user who has not engaged first. Every supported trigger (`comment_keyword`, `story_reply`, `dm_reaction`, `dm_keyword`) is anchored to such an engagement, which is what makes the send permissible. > [accordion] Why does an activity say `sent` but the recipient never got the DM? > > `sent` means Meta **accepted** the message, not that it was delivered. This is true on both Instagram and Facebook (Messenger from your Page): the automation records acceptance only and does not track delivery. On Instagram, delivery depends on the recipient's Instagram **Message requests** setting — if they don't allow message requests from everyone, Meta returns a success response and silently drops the message, with no error, webhook, or other signal on any API surface. A successful comment-triggered DM also arrives as a **message request the recipient must accept** (unless a conversation already exists). This is a permanent Instagram platform limitation. See [Automation DM Sent but Not Delivered](/docs/help-center/technical-support/automation-dm-sent-but-not-delivered). > [accordion] What happens if my access token is invalid when an automation fires? > > If the account's Instagram or Facebook Page credentials or messaging permissions genuinely fail — for example an expired or revoked access token, a missing Facebook Page selection, or Messaging not activated for the profile — the activity row records status `auth_error` and the DM is not retried. Resolving the account state (relinking, selecting a Page, or activating Messaging) lets the next matching engagement fire normally. This only applies to genuine credential and permission failures: if a specific DM could not be delivered for another reason — for example the recipient could not be found, or the triggering engagement came from the account that would send the DM — the row is recorded as `failed` or `skipped` with the reason on `actionResults[].errorDetails`, and relinking will not change the outcome. > [accordion] Why is there a delay before the DM is sent? > > Each dispatch is scheduled 20–60 seconds after the engagement, so DM sends look organic to Instagram's anti-spam systems. The delay is applied to the engagement **before** any rule is matched, so it applies to every action on the rule, `fire_webhook` and `send_email` included — expect your webhook to arrive 20–60 seconds after the comment, not immediately. The activity row's `created` timestamp is when the trigger matched; `completedAt` is when dispatch finished. > [accordion] Are activity rows kept forever? > > Activity rows are retained indefinitely for trace and analytics. The `GET /automations/:id/activity` endpoint returns rows from the last 30 days for performance. (The dedup guard uses its own per-action window — defaulting to 7 days — which is unrelated to the activity lookback.) > [accordion] Does deleting an automation remove its activity history? > > No. Delete is a soft-delete: the master row is flagged `deleted`, no new dispatches occur, but historical activity rows remain readable via the activity endpoint. ## Endpoints * [`POST /automations`](/docs/apis/automations/create-automation) — create a new automation * [`GET /automations`](/docs/apis/automations/list-automations) — list your automations * [`GET /automations/:id`](/docs/apis/automations/get-automation) — fetch one automation with its triggers and actions * [`PUT /automations/:id`](/docs/apis/automations/update-automation) — partial update; pause via `active: false` * [`DELETE /automations/:id`](/docs/apis/automations/delete-automation) — soft-delete * [`GET /automations/:id/activity`](/docs/apis/automations/get-activity) — cursor-paginated dispatch audit log # Update Automation Source: https://www.ayrshare.com/docs/apis/automations/update-automation PUT /automations/:id Partially update an automation's name, description, active status, triggers, or actions. Sending triggers or actions replaces the existing set atomically. > [!NOTE] > > **Beta.** See the [Automations Overview](/docs/apis/automations/overview) for the full feature description. Partial update. Only the listed fields are editable; sending anything else (e.g. `platform`, `accountId`) is rejected as a validation error. Sending `triggers` or `actions` **replaces** the existing children atomically: the old set is deleted and the new set is written in a single Firestore transaction. To change only one trigger, send the full new array. Re-activating a previously-inactive automation (`active: true`) re-checks the active-cap. If the cap is already at the limit, the update fails with code `470` and no changes are made. ## Header Parameters **Authorization** `string` *required* [API Key](/docs/apis/overview#authorization) of the Primary Profile. Format: `Authorization: Bearer API_KEY` **Profile-Key** `string` [Profile Key](/docs/apis/overview#profile-key-format) of a User Profile. Format: `Profile-Key: PROFILE_KEY` ## Path Parameters **id** `string` *required* The automation ID returned from `POST /automations`. ## Body Parameters **name** `string` New name. **description** `string` New description. **active** `boolean` Toggle the automation on or off. Setting this from `false` to `true` re-checks the active automation cap. **triggers** `array` Full replacement set of triggers (1–50). Same shape as the create endpoint. **actions** `array` Full replacement set of actions (1–50). Same shape as the create endpoint. ```bash cURL theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "name": "Spring promo (updated)", "active": true, "actions": [ { "type": "send_dm", "message": "Hey {{recipient_username}}! New link: https://example.com/spring" } ] }' \ -X PUT https://api.ayrshare.com/api/automations/auto_9xKp2Lm4nQ ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; const id = "auto_9xKp2Lm4nQ"; fetch(`https://api.ayrshare.com/api/automations/${id}`, { method: "PUT", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Spring promo (updated)", active: true, actions: [ { type: "send_dm", message: "Hey {{recipient_username}}! New link: https://example.com/spring", }, ], }), }) .then((res) => res.json()) .then((json) => console.log(json)) .catch(console.error); ``` ```python Python theme={"system"} import requests headers = { "Authorization": "Bearer API_KEY", "Content-Type": "application/json", } automation_id = "auto_9xKp2Lm4nQ" payload = { "name": "Spring promo (updated)", "active": True, "actions": [ { "type": "send_dm", "message": "Hey {{recipient_username}}! New link: https://example.com/spring", } ], } r = requests.put( f"https://api.ayrshare.com/api/automations/{automation_id}", json=payload, headers=headers, ) print(r.json()) ``` ```php PHP theme={"system"} $id = "auto_9xKp2Lm4nQ"; $data = [ "name" => "Spring promo (updated)", "active" => true, "actions" => [ [ "type" => "send_dm", "message" => "Hey {{recipient_username}}! New link: https://example.com/spring", ], ], ]; $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ayrshare.com/api/automations/" . $id, CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => [ "Authorization: Bearer API_KEY", "Content-Type: application/json", ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```json 200: Success theme={"system"} { "status": "success", "id": "auto_9xKp2Lm4nQ" } ``` ```json 400: Validation failed — editing platform is not allowed theme={"system"} { "action": "request", "status": "error", "code": 473, "message": "Validation failed. Please see: https://www.ayrshare.com/docs/introduction", "details": { "formErrors": ["Unrecognized key: \"platform\""], "fieldErrors": {} } } ``` ```json 404: Not found theme={"system"} { "action": "automation", "status": "error", "code": 469, "message": "Automation not found" } ``` ```json 429: Cap reached on reactivation theme={"system"} { "action": "automation", "status": "error", "code": 470, "message": "Active automation limit reached for your plan tier" } ``` # Brand API: Public Account & Competitor Data Source: https://www.ayrshare.com/docs/apis/brand/overview Use the Ayrshare Brand API to pull public profile, follower, and engagement data for any social account, to track your brand or benchmark competitors. > [!NOTE] > > **These endpoints have moved.** The Brand section has been reorganized under the new [Listening](/docs/apis/listen/overview) section. All existing Brand endpoints continue to work, but new features like [Keyword Search](/docs/apis/listen/keyword/search-tweets) are available only in the Listening section. # Delete Comments Source: https://www.ayrshare.com/docs/apis/comments/delete-comments DELETE /comments/:id Delete a single comment or all comments under a post sent via Ayrshare, or delete comments sent outside of Ayrshare using the Social Comment ID. > [!NOTE] > > **Targeting X/Twitter?** Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request: > > `X-Twitter-OAuth1-Api-Key` — Your API Key (Consumer Key) > > `X-Twitter-OAuth1-Api-Secret` — Your API Key Secret (Consumer Secret) > > **One-time setup per Ayrshare account.** You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do *not* create a new app per customer. > > Not linked yet? See the [full setup guide](/docs/dashboard/connect-social-accounts/x-twitter-byo-keys) to connect your X account. > > Your keys are never logged or stored by Ayrshare. The delete endpoint allows you to either delete comments sent via Ayrshare or comments that were sent outside of Ayrshare. Please see the [Comments Overview](/docs/apis/comments/overview) for more information on the different ID types. ### Delete Comments Sent from Ayrshare Delete either a single comment or all comments under a post that were sent via Ayrshare. Please see the [Ayrshare Post ID](/docs/apis/comments/overview#comments-with-ayrshare-post-id) and [Ayrshare Comment ID](/docs/apis/comments/overview#comments-with-ayrshare-comment-id) for more information. Supported platforms: Bluesky, Facebook, Instagram, LinkedIn, Reddit, TikTok, X/Twitter, and YouTube. > [!NOTE] > > **YouTube comments older than 28 days.** Ayrshare keeps the record of a YouTube comment it sent for 28 days, to stay within the 30-day limit in YouTube's API policies. After that, the Ayrshare ID no longer finds the comment. To delete it, use its [Social Comment ID](/docs/apis/comments/overview#comments-with-social-comment-id) (the YouTube comment `commentId`) with `"searchPlatformId": true`. ### Delete Comments Sent Outside of Ayrshare Delete a comment that was not sent via Ayrshare by using the `commentId` returned for a particular social network. This is the [Social Comment ID](/docs/apis/comments/overview#comments-with-social-comment-id) from the social networks, not the Ayrshare ID. Supported platforms: Bluesky, Facebook, Instagram, Threads, TikTok, X/Twitter, and YouTube. > [!NOTE] > > **TikTok — own-authored comments only.** On TikTok, `DELETE /comments` only succeeds for comments authored by the authenticated TikTok account itself (for example, replies you posted via Ayrshare's [reply endpoint](/docs/apis/comments/reply-to-comment) or directly inside the TikTok app). Attempting to delete a comment authored by another user — even one left on a video you own — returns Ayrshare `code: 328`. If you need to moderate third-party comments on your own TikTok videos, contact support so we can confirm what's available for your linked account type. For example, you get all the comments for a particular Instagram post using the [Get Comments](/docs/apis/comments/get-comments) endpoint with the `searchPlatformId` set to `true`. ```http theme={"system"} GET https://api.ayrshare.com/api/comments/18231730279304111?platform=instagram&searchPlatformId=true ``` The returned JSON will have a `commentId` for each comment, which you can use to delete the comment. Remember to set the `searchPlatformId` to `true`. ```json {5} theme={"system"} { "instagram": [ { "comment": "What an amazing comment", "commentId": "17969247335804735", "created": "2024-11-26T11:49:00Z", "from": { "id": "103038435208332", "username": "john_smith" }, "hidden": false, "likeCount": 3, "platform": "instagram", "postId": "18231730279304333", "username": "john_smith" } ] } ``` ## Header Parameters **Authorization** `string` *required* [API Key](/docs/apis/overview#authorization) of the Primary Profile. Format: `Authorization: Bearer API_KEY` **Profile-Key** `string` [Profile Key](/docs/apis/overview#profile-key-format) of a User Profile. Format: `Profile-Key: PROFILE_KEY` ## Path Parameters **id** `string` *required* Delete a comments sent from Ayrshare: