自動化 API 概觀

Beta。 Automations API 目前為 Beta 階段，我們正積極收集意見回饋。端點、payload 與限制在我們迭代的過程中可能會變動。請將意見與錯誤回報寄給 support，好讓我們能優先安排正確的改進項目。

Automations 端點讓你可以定義規則，自動回應進入的 Instagram 互動事件與 Facebook 粉絲專頁 DM。每個自動化配對一個或多個觸發條件（trigger）（觸發該規則的事件）與一個或多個動作（action）（觸發時發生的事）。單一規則可以監聽多個觸發條件並派送多個動作 — 讓同一次互動同時觸發一個進到你分析管線的 webhook，並發送一則 DM。引擎只會回應使用者主動導向你的互動事件（留言、限時動態回覆、DM 或表情回應）— 絕不會因為追蹤而發送 DM、也不會主動對陌生人發送第一則 DM，或執行大量對外發送 — 並沿用 Ayrshare 的每帳號速率限制、每接收者去重與具冪等性的 webhook 接收機制。

sent 表示 Meta 接受了訊息，並非代表接收者收到了訊息。 在 Instagram 上，訊息能否送達最終取決於接收者的 Message requests 設定：若對方不允許所有人傳送訊息請求，Meta 會回傳成功回應並靜默地將訊息捨棄，且此情況在任何 API 層面都完全不可見。即使是成功送達的留言觸發 DM，也是以接收者必須接受的訊息請求形式出現（除非兩個帳號之間已存在對話）。完整說明請見 Automation DM Sent but Not Delivered。

運作方式

建立自動化

透過 POST /automations 帶入你想要的觸發條件與動作。自動化會立即啟用。

終端使用者互動

有人在你的貼文留言、回覆你的限時動態、傳送 DM 或對 DM 表情回應。Meta 會將 webhook 送達 Ayrshare。

Ayrshare 比對並派送

為符合 Instagram 的反垃圾訊息啟發式規則，互動事件本身會先套用 20–60 秒的抖動延遲。之後引擎才會查找所有符合該事件的規則，檢查每個動作的去重與你的每日 DM 上限，然後執行每個動作。

檢視實際觸發狀況

GET /automations/:id/activity 會回傳稽核紀錄 — 每一次派送嘗試、每個動作的結果，以及任何錯誤。

觸發條件（Triggers）

單一自動化最多可附加 50 個觸發條件。每個觸發條件都是以 type 欄位為判別欄位的可辨聯集；type 專屬的欄位位於同一層。平台欄位列出每個觸發條件可用的平台；Facebook 所需的設定請見 Facebook 粉絲專頁。

Type	觸發時機	平台	設定
`comment_keyword`	貼文或 Reel 出現符合關鍵字的留言	`instagram`	`postId`（必填 — 貼文 ID，或 `"all"`）；`keywords`（必填，≥1 個）
`story_reply`	使用者透過 DM 回覆限時動態	`instagram`	`storyId`（選填 — 限時動態 ID，或 `"all"`）
`dm_reaction`	使用者以表情符號對你的 DM 表情回應	`instagram`, `facebook`	`emoji`（選填 — 省略則對任何表情符號都觸發）
`dm_keyword`	使用者傳送內文符合關鍵字的 DM	`instagram`, `facebook`	`keywords`（必填，≥1 個）

關鍵字比對不區分大小寫，且以完整字詞比對。當事件包含任一設定的關鍵字時，即滿足關鍵字過濾的觸發條件。

以 `"all"` 建立常青規則

將 postId（或 storyId）設為字面的小寫字串 "all"，即可對已連結帳號上的每一則貼文、Reel 或限時動態觸發，而非僅針對某一則特定內容。若你希望規則在新內容發布後仍持續運作、且不需為每則貼文呼叫一次 API，這就是你要的設定：

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

值必須剛好是 "all"。像 "ALL" 或 " all" 這類變體會被拒絕並回傳驗證錯誤，而不會被儲存為一個永遠比對不到的貼文 ID。 "all" 絕不會擴及已連結帳號以外的範圍 — 一個 profile 上的規則無法對另一個 profile 的內容觸發。你的每日 DM 上限與錨定於互動事件的發送規則，與單一貼文規則完全相同地適用。

去重是以每個自動化與接收者計算，而非以每則貼文計算。在 "all" 規則上，若使用者在去重視窗（預設 7 天）內於兩則不同貼文留言關鍵字，只會收到一次 DM；第二筆活動會記錄為 deduplicated。較小的 dedupWindowMinutes 只會縮短該視窗，並不會讓去重變成以每則貼文計算。設為 0 會關閉去重，因此每則符合的留言都會發送 DM，包括在同一則貼文上的重複留言。

在限時動態觸發條件上，省略 storyId 的行為與 "all" 相同。請優先使用 "all" — 它明確表達意圖，且省略的用法將在未來版本淘汰，並會提前於 Upcoming API Changes 公告。

Facebook 粉絲專頁

將 platform 設為 facebook，即可在與該 profile 連結的 Facebook 粉絲專頁上執行自動化。DM 會透過 Messenger 從粉絲專頁發送。

觸發條件： dm_keyword 與 dm_reaction。留言與限時動態觸發條件目前僅限於 Instagram，使用這類觸發條件的 Facebook 自動化會被以驗證錯誤拒絕。
Messaging： 該 profile 需要為 Facebook 啟用 Messaging，與使用 Messages API 發送 Facebook DM 的要求相同。
接收者： {{recipient_id}} 是使用者的粉絲專頁範圍 ID（PSID）。{{recipient_username}} 為空，因為 Messenger webhook 不包含使用者名稱。

{
  "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" }]
}

動作（Actions）

單一自動化最多可附加 50 個動作。它們會依序執行，每個結果都會記錄在該活動列上。

Type	效果	設定
`send_dm`	使用模板化訊息或每次觸發時由你產生的文字，向觸發規則的使用者發送 DM（Instagram，或透過 Messenger 從你的 Facebook 粉絲專頁發送）。	`message`（必填，支援模板）；`messageUrl`（選填）；`timeoutMs`（選填）
`fire_webhook`	將自動化上下文以 POST 送到你的帳號層級 webhook URL（請透過 `POST /hook/webhook` 設定）。	`sendCompletedEvent`（選填，boolean — 也發送 `automation.completed`）。payload 格式固定；請見下方
`send_email`	透過平台的郵件管線將郵件排入佇列。	`to`（必填，email）；`subject`（選填，支援模板）；`message`（必填，支援模板）

每個動作的去重視窗

無論動作類型為何，每個動作都額外接受一個選填的最外層 dedupWindowMinutes 欄位，可為該動作覆寫預設 7 天的每接收者去重視窗。

設為 0 可為該動作完全停用去重（fire_webhook / send_email 通常會這樣，因為接收方預期收到每個事件）。
上限為 525600（一年）。

Action with a 24h dedup override

{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}

動態訊息內容

預設情況下，send_dm 會向每位觸發規則的人發送相同的 message。像 {{recipient_username}} 這類預留變數，是唯一會因人而異的部分。在動作上設定 messageUrl，就改由你自己的伺服器為每個人撰寫 DM：每當規則比對成功，我們會詢問你的端點要說什麼，再將它的回應當作 DM 發送。 範例。 你的規則會回覆任何在貼文留言「LINK」的人，而 messageUrl 指向你的伺服器。當 Ava 留言「LINK please!」時：

我們將詳細資訊以 POST 送到你的 messageUrl：誰留言（"recipientUsername": "ava"）、寫了什麼，以及留言在哪則貼文上。
你的伺服器為 Ava 撰寫回覆，例如附上專為她產生的追蹤連結，並回應 { "message": "Hi ava, here's your link: https://example.com/r/12345" }。
我們將該文字原封不動地以 DM 發送給 Ava。

若你的伺服器未在 timeoutMs 內回應、回傳錯誤，或回傳我們無法使用的內容，我們會改為發送該動作的一般 message 給 Ava，讓她仍能收到回覆。像這樣將它加到 send_dm 動作中：

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 是我們請求文字的位置。message 仍為必填，並作為備援：它絕不會被送到你的伺服器，而每當你的伺服器未及時回應、回傳錯誤，或回傳我們無法使用的內容時（請見下方警告），我們就會改以它發送 DM。timeoutMs 為選填（預設 3000，上限 5000）。 我們傳給你端點的內容。 一個帶有以下 JSON 本文的 POST：

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
}

欄位	意義
`automationId`, `triggerId`, `trigger`, `platform`	是哪個自動化與觸發條件被觸發，與 `fire_webhook` payload 相同
`recipientId`, `recipientUsername`	DM 的接收者。當觸發條件未帶有使用者名稱時（例如 `dm_keyword`），`recipientUsername` 為 `null`
`keyword`	比對成功的關鍵字，或 `null`
`activityId`	此次觸發的活動項目，方便你與 `GET /automations/:id/activity` 對應
`actionId`	發出請求的是哪個 `send_dm` 動作，與 `actionResults[].actionId` 對應。讓單一端點可服務同一自動化上的多個 `send_dm` 動作
`eventId`	我們為造成此次觸發的互動事件所給的 id
`commentId`	留言觸發條件的 Instagram 留言 id；DM 與限時動態觸發條件為 `null`
`commentText`	比對成功的文字：留言、DM 或表情回應的 emoji。若無則為 `null`（例如 `story_reply`）
`postId`, `storyId`	互動事件發生所在的貼文或限時動態，或 `null`
`timestamp`	我們發出請求的時間，ISO 8601 格式
`timeStamp`	以 Unix 時間（秒）表示的同一時間點。僅在回呼有簽章時出現，與我們的 webhook 相同

若你已註冊 webhook secret，本文會以與你的 automations webhook 相同的 secret、相同的方式簽章：X-Authorization-Content-SHA256 是原始本文的 HMAC-SHA256，而 X-Authorization-Timestamp 帶有本文的 timeStamp。你現有用於驗證我們 webhook 的程式碼無需修改即可使用。若已註冊 secret 但我們當下無法讀取它，我們不會發送未簽章的回呼，而是改為發送你的 message 模板。 可以指向哪裡。 messageUrl 必須是公開的 HTTPS 位址。解析到私有、loopback、link-local 或雲端中繼資料位址的 URL 會被拒絕，且不會跟隨重新導向 — 3xx 回應視為失敗。無論哪種情況，都會改為發送模板。 你的端點要回傳什麼。 回傳 200 與一個 JSON 本文，大小最多 16 KB，其中包含長度 1 到 1000 個字元的 message 字串：

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

你的文字會被逐字發送。它不會套用 {{placeholder}} 替換，因此你產生的文字中若有字面上的 {{，會原樣送達接收者。

message 仍為必填，而且不是裝飾用的。 若你的端點逾時、回傳非 2xx、回傳我們無法使用的本文，或因多次失敗而被暫時熔斷，我們會改為發送渲染後的 message 模板。這次發送仍可能失敗，例如模板渲染結果為空（請見下方）或 Instagram 拒絕了它。我們絕不會重試回呼 — 重試可能導致接收者收到兩則訊息。

timeoutMs 預設為 3000。上限為 5000：在建立或更新自動化時，較大的值會被以驗證錯誤拒絕。它涵蓋整個交換過程，包括讀取你的回應本文。請預留這段時間：DM 會在你的端點回應後才發送，因此較慢的端點會延遲訊息。可在 GET /automations/:id/activity 查看某次觸發走的是哪條路徑。actionResults[] 中的 send_dm 項目在 DM 文字確定後就會帶有 messageSource，即使之後發送失敗也一樣。若動作在那之前就已停止，例如發給你自己帳號而被 skipped 的 DM，或 deduplicated 的動作，則不會出現此欄位：

`messageSource`	意義
`template`	未設定 `messageUrl`；使用了靜態的 `message`
`callback`	你的端點已回應，並使用了它的文字
`fallback`	已設定 `messageUrl` 但無法使用；改為使用 `message`

messageSource 說明的是 DM 以哪段文字建立，而非是否已送達。送達與否請看該項目的 status。單純的備援本身不會讓動作失敗：當模板 DM 送達時，該項目為 sent，而未使用回呼的原因會記在 errorDetails。若模板 DM 也發送失敗，該項目為 failed，且 errorDetails 會提供發送錯誤，後接回呼的原因。請留意這一點：否則每次觸發都失敗的回呼，看起來會和正常運作的回呼完全一樣。請確保你的 message 本身即可發送。若它對某位接收者渲染結果為空，例如在未帶有使用者名稱的 DM 觸發條件上只使用 {{recipient_username}}，而你的回呼文字又未被使用，則不會發送任何 DM，且該動作為 failed，原因記在 errorDetails。

Webhook 事件

有兩種事件會送達你透過 POST /hook/webhook 註冊的 automations webhook 動作。兩者都帶有 type 欄位 — 請先依此欄位分支處理，再讀取其他任何內容。

`type`	發送時機
`automation.triggered`	規則的 `fire_webhook` 動作執行時
`automation.completed`	派送完成時，附帶其結果

automation.completed 預設為關閉。要為某個自動化開啟它，請在其 fire_webhook 動作上設定 "sendCompletedEvent": true。未設定時會維持關閉，因此為「每次觸發一個 payload」而建置的接收端仍然會收到剛好一個。automation.triggered 並不是每次比對成功的紀錄：它只在 fire_webhook 本身執行時發送，因此以 rate_limited 或 deduplicated 結束的比對只會產生 automation.completed。若自動化在派送執行前已被停用或刪除，這兩種事件都不會發送。

`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 就是 GET /automations/:id/activity 回傳的資料列，因此你可以將兩者精確地關聯，而不必用 recipientId + triggerId + keyword 比對 — 當多人同時留言同一個關鍵字時，那種比對方式會產生歧義。actionId 是發送此事件的 fire_webhook 動作，且與 actionResults[].actionId 相符；它能區分同一規則上的兩個 fire_webhook 動作。觸發條件沒有帶入的欄位會是 null 而非省略，因此格式是穩定的。recipientUsername 在 dm_keyword、dm_reaction 與 story_reply 時為 null，因為 Meta 的 payload 不包含 username。commentId 僅在 comment_keyword 與 story_comment 時設定，postId 僅在 comment_keyword 時設定，storyId 僅在限時動態觸發條件時設定。story_reply 沒有 keyword。就 dm_keyword 而言，commentText 是 DM 內文；就 dm_reaction 而言，commentText 與 keyword 都是該表情回應的表情符號。

`automation.completed`

僅在自動化於其 fire_webhook 動作上選擇加入時發送：

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 與每個 actionResults[].status 使用與活動紀錄相同的值 — sent、failed、rate_limited、deduplicated、skipped、auth_error — 因此在一般情況下，你不需輪詢即可得知派送的結果。不過此事件的送達是盡力而為：若程序在記錄結果與將事件排入佇列之間停止，該事件就不會發送。活動紀錄才是事實的紀錄，因此若你需要每一個結果，請針對任何尚未回報結果的 activityId，比對 GET /automations/:id/activity 進行核對。send_dm 結果也會帶有 messageSource，與活動紀錄相同：template、callback 或 fallback，讓你不需輪詢就能發現持續走備援的 messageUrl。請以 actionId 將結果對應到你設定的動作，而非依位置 — 兩個相同類型的動作只能靠這種方式區分。actionResults 在三種情況下會是空的，且各自的原因（若有）會記在最外層的 errorDetails：rate_limited（已達你的每日上限）、deduplicated（每個動作都在其去重視窗內），以及派送重試達最大次數仍未完成後的 failed。在最後一種情況下，部分動作可能已經執行，因此 DM 可能已經送出，automation.triggered 也可能已經發送。 Webhook 的送達為至少一次（at-least-once），因此同一事件偶爾可能送達兩次，且被重試的派送可能以新的 hookId 再次發送 automation.triggered。絕對不要以 hookId 去重。請為每種事件類型分別設定鍵值，讓處理其中一個絕不會抑制另一個：automation.completed 以 activityId 為鍵（每個活動只有一個結果），automation.triggered 以 activityId 加上 actionId 為鍵（每個 fire_webhook 動作各一）。這兩種事件是各自獨立送達的，因此 automation.completed 偶爾可能比 automation.triggered 更早到達。

若未註冊任何 webhook

fire_webhook 會 POST 到該 profile 上註冊的 automations 動作，並在沒有時回退到你的 Primary Profile。它不會回退到其他動作（例如 messages）。若兩者都未註冊，automation.triggered 不會被靜默捨棄：該動作會在活動列上記錄為 failed，原因記在 actionResults[].errorDetails。（automation.completed 同樣無處可送，且不會被記錄。）該次派送的整體狀態接著會依循一般的優先順序：若任一動作發生驗證錯誤則為 auth_error，否則若任一動作被接受則為 sent，否則為 failed。因此，只有在規則上沒有其他動作成功發送時，缺少 webhook 才會計入自動化的失敗統計；當其他動作確實發送成功（且沒有動作發生驗證錯誤）時，該次派送會以 sent 結束，失敗的 webhook 只會顯示在 actionResults[] 中。 fire_webhook 的結果為 sent 表示事件已排入佇列，準備送達你的 URL，並不代表你的端點接受了它。之後的送達會依其自身的排程重試。

模板變數

send_dm.message、send_email.subject 與 send_email.message 支援 {{placeholder}} 替換。未知的預留變數會在建立/更新時被拒絕（回傳 473 驗證錯誤），因此打字錯誤絕不會靜默地讓字面上的 {{foo}} 洩漏到對客戶顯示的訊息中。

預留變數	對應內容
`{{recipient_username}}`	互動使用者的 Instagram handle（僅限留言觸發條件）。在 DM 與限時動態回覆觸發條件中為空，在 Facebook 上一律為空
`{{recipient_id}}`	互動使用者的 ID：在 Instagram 上為 Instagram 範圍 ID（IGSID），在 Facebook 上為粉絲專頁範圍 ID（PSID）
`{{recipient_name}}`	保留欄位；在未來的資料增補來源填入之前，會解析為空字串
`{{sender_username}}`	保留欄位；目前在所有平台上都會解析為空字串
`{{sender_name}}`	保留欄位；目前在所有平台上都會解析為空字串
`{{comment_text}}`	觸發規則的留言 / DM / 限時動態回覆的文字
`{{comment_id}}`	觸發訊息的平台端 id
`{{comment_sent_at}}`	事件的 ISO 8601 時間戳（若有提供）
`{{matched_keyword}}`	比對到的關鍵字（`dm_reaction` 則為 emoji 字串）
`{{platform}}`	平台識別碼：`instagram` 或 `facebook`
`{{trigger_type}}`	觸發條件類型（例如 `comment_keyword`）

沒有 sender_email / recipient_email。 這些是刻意不公開的 — 你的帳單 email 沒有正當理由出現在傳給陌生人的 DM 中，而且 Meta 也不會在任何 IG webhook 上提供接收者的 email。不提供這些預留變數可避免意外洩漏。

模板範例：

Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com

速率限制與上限

方案	使用中的自動化數（每個 profile）	每日 DM 上限（每個帳號）
Launch & Business	10	1,000
Enterprise	50	5,000

使用中的自動化上限是以每個 User Profile 計算，而非以父帳號計算。你帳號底下的每個 profile 都各自有 Launch/Business 10 或 Enterprise 50 的額度，因此一個擁有許多 profile 的帳號，可以在每個 profile 上執行相對應數量的自動化。此上限會計算使用中的自動化，並在 POST（建立）與 PUT 重新啟用（active: false → true）時強制執行，兩者都會回傳錯誤代碼 470。若你需要提高每個 profile 的上限？請聯絡支援為你的帳號調整。 每日 DM 上限依父 Ayrshare 帳號計算，由你所有 profile 共用，並額外設有每個 profile 的子上限，讓單一忙碌的 profile 無法耗盡整個帳號的配額。當觸及 DM 上限時，該活動列會記錄狀態為 rate_limited，且不會發送 DM。 訊息對話上限同樣適用。send_dm 需要該 profile 啟用 Messaging 附加功能，且它傳送的每則 DM 都會計入該 profile 的每月對話上限，與你自行傳送的 DM 相同。達到上限時，傳送給新收件者的 send_dm 不會發送，該活動列會記錄狀態為 failed，並在 actionResults[].errorDetails 中附上上限訊息。由留言觸發的 DM（comment_keyword 與 story_comment）是例外：達到上限時仍會發送，且仍會計入。單一自動化的結構性上限：1–50 個觸發條件、1–50 個動作。 Instagram 本身對每個帳號的 DM 上限約為每小時 200 則。引擎會以 20–60 秒的抖動延遲派送，以安全地維持在此門檻之下。

活動狀態

GET /automations/:id/activity 中的每一列都有最外層的 status，以及 actionResults[] 中每個動作的 status：

狀態	意義
`pending`	剛寫入；worker 尚未取用
`in_flight`	worker 正在派送中
`sent`	至少一個動作被平台接受，且沒有動作發生驗證錯誤。就 `send_dm` 而言，這表示 Meta 接受了該訊息 — 但不代表接收者收到了訊息（請見下方說明）
`failed`	沒有任何動作被接受，且至少一個動作被平台拒絕或無法執行（且沒有動作發生驗證錯誤）。原因會記在 `actionResults[].errorDetails`
`auth_error`	該帳號的 Instagram 或 Facebook 粉絲專頁憑證或訊息傳遞權限無法使用 — 例如已過期或已撤銷的存取權杖、未選擇 Facebook Page，或該 profile 未啟用 Messaging。DM 沒有被重試。每個接收者的送達失敗會記錄為 `failed`，而不會記在此處
`rate_limited`	已達每日 DM 上限（方案層級或每個 profile）；DM 未被發送
`deduplicated`	此動作已於其去重視窗內對此接收者觸發過
`skipped`	該自動化在派送前被抑制 — 在 fan-out 與派送之間被停用或已刪除、未設定任何動作，或觸發它的互動事件來自該自動化自己的帳號 — 最常見的情況是對自己的貼文留言。在最後這種情況下不會執行任何動作：不會發送 DM（帳號無法傳訊息給自己），`fire_webhook` 與 `send_email` 也不會執行。已選擇加入 `automation.completed` 的自動化仍會收到該事件，並帶有此狀態

pending 與 in_flight 為暫時狀態；其他皆為終態。當自動化有多個動作時，最外層的 status 會依以下順序從每個動作的結果導出：若任一動作發生驗證錯誤則為 auth_error，接著若任一動作被接受則為 sent，接著若每個動作皆被去重則為 deduplicated，接著若每個動作皆被刻意抑制（skipped 或 deduplicated）則為 skipped，否則為 failed。請閱讀 actionResults[] 取得每個動作的詳細資訊。

sent 只是平台的接受回執，並不是送達回執。 當 Meta 接受訊息的當下，該 send_dm 動作就會被標記為 sent，無論訊息是從你的 Instagram 帳號發出，還是透過 Messenger 從你的 Facebook 粉絲專頁發出。自動化只記錄這次接受，不會追蹤送達狀態。Instagram 不會透過任何 API 揭露訊息送達狀態，接收者是否實際收到，則取決於他們的 Instagram Message requests 設定，而 Ayrshare 既無法讀取也無法影響該設定。請參閱 Automation DM Sent but Not Delivered。

錯誤代碼

API 會回傳兩種錯誤形態：

業務規則錯誤會帶有編號的自動化 code（例如 { "action": "automation", "code": 469, ... }）。
驗證錯誤 — 任何格式不正確的請求主體（欄位缺失或無效、未知的模板變數、無法辨識的鍵）— 會回傳單一 473 回應，並附上 details 物件列出違規的欄位。details 是驗證器的輸出（formErrors 加上 fieldErrors）。請以 details 為分支依據，而非為每個條件另設代碼。在 fieldErrors 中，鍵是最外層的請求欄位（triggers、actions）：特定項目內部的問題（例如某個觸發條件缺少 keywords）會回報於該欄位（例如 triggers）；formErrors 則保留物件層級的問題，例如無法辨識的鍵。

Code	HTTP	意義
468	403	需要 Business 或 Enterprise 方案
469	404	找不到自動化（呼叫者非擁有者時也會回傳）
470	429	已達方案層級的使用中自動化上限
471	400	此 profile 在指定平台上未連結社群帳號
472	403	你的帳號尚未啟用此功能 — 若想搶先體驗請與我們聯絡
473	400	驗證失敗（請求主體格式錯誤）— 請檢查 `details`

Launch 方案同樣包含在內。 Business Launch 會歸入 Business 層級，因此 Launch、Business 與 Enterprise 方案都可以使用自動化。468 僅會回傳給不包含自動化的方案。

Meta 不允許的功能

有些常被要求的功能因 Meta 不允許在公開的 Instagram API 上使用，因此不支援：

對新粉絲自動 DM。 Instagram 不會發布「追蹤」的 webhook。
對陌生人主動發送第一則 DM。 Meta 要求接收者必須先有互動（留言、回覆、DM、表情回應），商業帳號才能傳送訊息給對方。這裡每個支援的觸發條件都錨定在這樣的互動事件上 — 但要注意，被允許發送並不等於訊息真的被送達：接收者的 Instagram Message requests 設定仍可能讓 Meta 接受訊息之後靜默地將其捨棄（請見 Automation DM Sent but Not Delivered）。
大量對外行銷發送。 平台層級套用每小時 DM 上限與反濫用啟發式規則。

多 Profile 使用

這些端點會遵循 profileKey 標頭。傳入子 profile 的 key，自動化就會在該 profile 下建立/管理。速率限制會透過每個 profile 的子上限分配，因此單一講話很多的 profile 不會耗盡父帳號的配額。

FAQ

我可以以新粉絲作為觸發條件嗎？

不行。Instagram 不會發布「追蹤」webhook，Meta 也不允許第三方 App 主動發送 DM 給尚未先有互動的使用者。每個支援的觸發條件（comment_keyword、story_reply、dm_reaction、dm_keyword）都錨定在這樣的互動事件上，這正是讓發送得以被允許的原因。

為什麼有的活動列顯示 sent，但接收者卻從沒收到 DM？

sent 表示 Meta 接受了訊息，並不表示訊息已送達。這在 Instagram 和 Facebook（透過 Messenger 從你的粉絲專頁發送）上都成立：自動化只記錄接受結果，不會追蹤送達狀態。在 Instagram 上，送達與否取決於接收者的 Instagram Message requests 設定 — 若對方不允許所有人傳送訊息請求，Meta 會回傳成功回應並靜默地將訊息捨棄，任何 API 層面都不會出現錯誤、webhook 或其他訊號。即使是成功的留言觸發 DM，也是以接收者必須接受的訊息請求形式出現（除非對話已經存在）。這是 Instagram 平台的長期限制。請參閱 Automation DM Sent but Not Delivered。

如果自動化觸發時我的存取權杖無效會怎樣？

若該帳號的 Instagram 或 Facebook 粉絲專頁憑證或訊息傳遞權限確實失效 — 例如已過期或已撤銷的存取權杖、未選擇 Facebook Page，或該 profile 未啟用 Messaging — 活動列會記錄狀態為 auth_error，且 DM 不會被重試。將帳號狀態解決（重新連結、選擇 Page，或啟用 Messaging）後，下一次符合條件的互動就會正常觸發。此僅適用於真正的憑證與權限失敗：若某則特定 DM 因其他原因無法送達 — 例如找不到接收者，或觸發它的互動事件來自將要傳送 DM 的帳號 — 該列會記錄為 failed 或 skipped，並將原因記在 actionResults[].errorDetails，重新連結並不會改變結果。

為什麼發送 DM 之前有延遲？

每次派送會在互動事件後 20–60 秒排程，好讓 DM 傳送對 Instagram 的反垃圾系統看起來更自然。此延遲在比對任何規則之前就套用在互動事件上，因此規則中的每個動作都會受到影響，包括 fire_webhook 與 send_email——你的 webhook 會在留言後 20–60 秒才送達，而不是立即送達。活動列的 created 時間戳為觸發條件比對到的時間；completedAt 為派送完成的時間。

活動列會永久保存嗎？

活動列會為了追蹤與分析而無限期保留。為了效能，GET /automations/:id/activity 端點僅回傳最近 30 天內的資料列。（去重機制使用自己的每個動作視窗 — 預設 7 天 — 與活動的查詢視窗無關。）

刪除自動化會一併移除其活動歷史嗎？

不會。刪除是軟刪除：主資料列會被標記為 deleted，不會再有新的派送，但既有的活動歷史仍可透過 activity 端點讀取。

端點

POST /automations — 建立新的自動化
GET /automations — 列出你的自動化
GET /automations/:id — 取得一個自動化及其觸發條件與動作
PUT /automations/:id — 部分更新；透過 active: false 暫停
DELETE /automations/:id — 軟刪除
GET /automations/:id/activity — 游標分頁的派送稽核紀錄

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

運作方式

觸發條件（Triggers）

以 `"all"` 建立常青規則

Facebook 粉絲專頁

動作（Actions）

每個動作的去重視窗

動態訊息內容

Webhook 事件

`automation.triggered`

`automation.completed`

若未註冊任何 webhook

模板變數

速率限制與上限

活動狀態

錯誤代碼

Meta 不允許的功能

多 Profile 使用

FAQ

端點

​運作方式

​觸發條件（Triggers）

​以 "all" 建立常青規則

​Facebook 粉絲專頁

​動作（Actions）

​每個動作的去重視窗

​動態訊息內容

​Webhook 事件

​automation.triggered

​automation.completed

​若未註冊任何 webhook

​模板變數

​速率限制與上限

​活動狀態

​錯誤代碼

​Meta 不允許的功能

​多 Profile 使用

​FAQ

​端點

運作方式

觸發條件（Triggers）

以 `"all"` 建立常青規則

Facebook 粉絲專頁

動作（Actions）

每個動作的去重視窗

動態訊息內容

Webhook 事件

`automation.triggered`

`automation.completed`

若未註冊任何 webhook

模板變數

速率限制與上限

活動狀態

錯誤代碼

Meta 不允許的功能

多 Profile 使用

FAQ

端點