自动化 API 概述

Beta。 自动化 API 目前处于 Beta 阶段，我们正在积极收集反馈。在我们进行迭代过程中，端点、载荷和限制可能会发生变化。请将反馈和缺陷报告发送给支持团队，以便我们优先安排合适的改进。

自动化端点让你可以定义规则，自动响应传入的 Instagram 互动和 Facebook 主页私信。每条自动化规则由一个或多个触发器（触发规则的事件）与一个或多个动作（触发时发生的操作）组成。一条规则可以监听多种触发器并派发多个动作——比如从同一次互动中同时向你的分析管线触发一个 Webhook，并发送一条私信。引擎只对用户主动向你发出的互动作出反应（评论、动态回复、私信或表情反应）——它绝不会发送基于关注触发的私信、向陌生人发送首条私信或批量对外群发——并且继承了 Ayrshare 的每账户速率限制、每收件人去重以及幂等 Webhook 接入。

sent 表示 Meta 已接受该消息，并不代表收件人已收到。 在 Instagram 上，投递最终由收件人的 Message requests 设置决定：如果他们不允许来自所有人的消息请求，Meta 会返回成功响应并静默丢弃该消息，而这在任何 API 层面都不可见。即便是投递成功的评论触发私信，也会作为收件人必须接受的消息请求送达（除非两个账户之间已存在会话）。完整说明请参见自动化私信已发送但未送达。

工作原理

创建自动化

调用 POST /automations，附上你想要的触发器和动作。自动化会立即激活。

终端用户产生互动

有人在你的帖子上评论、回复你的动态、发送私信或对私信做出表情反应。Meta 会将 Webhook 投递给 Ayrshare。

Ayrshare 匹配并派发

为了保持在 Instagram 的反垃圾启发式规则之内，互动本身会先应用 20–60 秒的抖动延迟。之后引擎才会查找所有与该事件匹配的规则，检查每个动作的去重设置和你每日的私信上限，然后运行每个动作。

查看触发情况

GET /automations/:id/activity 返回审计日志——每次派发尝试、每个动作的结果以及任何错误。

触发器

一条自动化最多可关联 50 个触发器。每个触发器基于 type 字段的可辨联合类型；特定类型的字段位于同一层级。平台列显示了每个触发器的可用范围；Facebook 的要求请参见 Facebook 主页。

类型	触发时机	平台	配置
`comment_keyword`	匹配关键词的评论出现在帖子或 Reel 上时	`instagram`	`postId`（必填——帖子 ID，或 `"all"`）；`keywords`（必填，≥1 项）
`story_reply`	用户通过私信回复动态时	`instagram`	`storyId`（可选——动态 ID，或 `"all"`）
`dm_reaction`	用户对你的某条私信作出表情反应时	`instagram`, `facebook`	`emoji`（可选——省略则任何表情都会触发）
`dm_keyword`	用户发送内容匹配关键词的私信时	`instagram`, `facebook`	`keywords`（必填，≥1 项）

关键词匹配不区分大小写且按整词匹配。如果事件包含任一已配置的关键词，即满足带关键词过滤器的触发器。

使用 `"all"` 的常青规则

将 postId（或 storyId）设为字面小写字符串 "all"，即可在所连接账户的每一条帖子、Reel 或动态上触发，而不是只针对某一条特定内容。当你希望规则在新内容发布后持续生效、且无需为每条帖子调用一次 API 时，这正是你想要的：

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

该值必须恰好是 "all"。诸如 "ALL" 或 " all" 之类的变体会作为验证错误被拒绝，而不会被保存为一个永远不会匹配的帖子 ID。 "all" 的范围绝不会超出所连接的账户——一个资料上的规则无法在另一个资料的内容上触发。你的每日私信上限以及锚定于互动的发送规则，与单帖规则完全一样地适用。

去重按自动化和收件人计数，而不是按帖子。在一条 "all" 规则上，某个用户在去重窗口（默认 7 天）内于两条不同的帖子上评论了关键词，只会收到一次私信；第二条活动会被记录为 deduplicated。更小的 dedupWindowMinutes 只会缩短该窗口；它不会让去重变成按帖子计。将其设为 0 会关闭去重，此时每条匹配的评论都会发送一条私信，包括同一帖子上的重复评论。

在动态触发器上，省略 storyId 的行为与 "all" 相同。请优先使用 "all"——它明确表达了意图，而省略方式将在未来版本中被淘汰，并会提前在即将进行的 API 变更上公告。

Facebook 主页

将 platform 设为 facebook，即可在与该资料关联的 Facebook 主页上运行自动化。私信将从该主页通过 Messenger 发送。

触发器： dm_keyword 和 dm_reaction。评论和动态触发器目前仅限 Instagram，使用这些触发器的 Facebook 自动化会因验证错误而被拒绝。
Messaging： 该资料需要为 Facebook 激活 Messaging，与使用 Messages API 发送 Facebook 私信的要求相同。
收件人： {{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" }]
}

动作

一条自动化最多可关联 50 个动作。它们依次执行；每个动作的结果都会记录在活动条目中。

类型	效果	配置
`send_dm`	使用模板化消息或每次派发时由你生成的文本，向触发规则的用户发送私信（Instagram 私信，或从你的 Facebook 主页通过 Messenger 发送）。	`message`（必填，支持模板）；`messageUrl`（可选）；`timeoutMs`（可选）
`fire_webhook`	将自动化上下文以 POST 请求发送到你账户级别的 Webhook URL（通过 `POST /hook/webhook` 配置）。	`sendCompletedEvent`（可选，boolean——同时发送 `automation.completed`）。载荷结构是固定的；见下文
`send_email`	通过平台的邮件管线排队发送邮件。	`to`（必填，邮箱地址）；`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 后，就由你自己的服务器为每个人撰写私信：每当规则匹配时，我们都会询问你的端点要发送什么内容，然后将其回答作为私信发送。 示例。 你的规则会回复任何在帖子下评论 “LINK” 的人，且 messageUrl 指向你的服务器。当 Ava 评论 “LINK please!” 时：

我们将详细信息 POST 到你的 messageUrl：谁发表了评论（"recipientUsername": "ava"）、写了什么，以及评论在哪个帖子上。
你的服务器为 Ava 撰写一条回复，例如附上专为她生成的追踪链接，并返回 { "message": "Hi ava, here's your link: https://example.com/r/12345" }。
我们将这段文本原样作为私信发送给 Ava。

如果你的服务器未在 timeoutMs 内应答、返回错误，或返回了我们无法使用的内容，我们会改为向 Ava 发送该动作的常规 message，确保她仍能收到回复。像这样将其添加到 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 仍为必填，并作为回退内容：它永远不会发送到你的服务器，每当你的服务器未及时应答、返回错误或返回我们无法使用的内容时（见下方警告），我们就改为以私信发送它。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` 载荷中相同
`recipientId`, `recipientUsername`	私信的接收人。当触发器不携带用户名时（例如 `dm_keyword`），`recipientUsername` 为 `null`
`keyword`	匹配到的关键词，或 `null`
`activityId`	本次派发对应的活动条目，便于你将其与 `GET /automations/:id/activity` 对应起来
`actionId`	发起请求的是哪个 `send_dm` 动作，与 `actionResults[].actionId` 匹配。使同一个端点可以服务同一条自动化上的多个 `send_dm` 动作
`eventId`	我们为引发本次派发的互动分配的 id
`commentId`	评论类触发器的 Instagram 评论 id；私信和快拍触发器为 `null`
`commentText`	匹配到的文本：评论、私信或反应表情。没有时为 `null`（例如 `story_reply`）
`postId`, `storyId`	互动所在的帖子或快拍，或 `null`
`timestamp`	我们发出请求的时间，ISO 8601 格式
`timeStamp`	同一时刻的 Unix 时间，以秒为单位。仅在回调已签名时出现，与我们的 Webhook 一致

如果你已注册 Webhook 密钥，正文会使用与你的 automations Webhook 相同的密钥、以相同方式签名：X-Authorization-Content-SHA256 是原始正文的 HMAC-SHA256，X-Authorization-Timestamp 携带正文中的 timeStamp。你现有的 Webhook 验证代码无需修改即可使用。如果已注册密钥但我们当时无法读取它，我们不会发送未签名的回调，而是改为发送你的 message 模板。 可以指向哪里。 messageUrl 必须是公网 HTTPS 地址。解析到私有、回环、链路本地或云元数据地址的 URL 会被拒绝，且不会跟随重定向——3xx 应答视为失败。无论哪种情况，都会改为发送模板。 你的端点应返回什么。 返回 200 及一个不超过 16 KB 的 JSON 正文，其中包含一个 1 到 1000 个字符的 message 字符串：

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

你的文本会被原样发送。它不会进行 {{placeholder}} 替换，因此你生成的文本中的字面 {{ 会按原样送达收件人。

message 仍为必填，而且并非摆设。 如果你的端点超时、返回非 2xx、返回我们无法使用的正文，或因多次失败而被暂时熔断，我们会改为发送渲染后的 message 模板。这次发送仍可能失败，例如模板渲染为空（见下文）或被 Instagram 拒绝。我们从不重试回调——重试可能导致收件人收到两条消息。

timeoutMs 默认为 3000。最大值为 5000：在创建或更新自动化时，更大的值会因验证错误而被拒绝。它涵盖整个交互过程，包括读取你的响应正文。请为此预留时间：私信在你的端点应答后才发送，因此端点响应慢会延迟消息。可在 GET /automations/:id/activity 上查看某次派发走的是哪条路径。一旦私信文本确定，actionResults[] 中的 send_dm 条目就会携带 messageSource，即使随后发送失败也是如此。如果动作在此之前就已停止，例如向你自己账户发送的 skipped 私信或 deduplicated 动作，则不含该字段：

`messageSource`	含义
`template`	未配置 `messageUrl`；使用了静态 `message`
`callback`	你的端点已应答，并使用了其文本
`fallback`	设置了 `messageUrl` 但不可用；改为使用了 `message`

messageSource 表示私信是基于哪段文本构建的，而不表示是否已投递。投递情况请查看条目的 status。回退本身并不会导致动作失败：当模板私信投递成功时，条目为 sent，未使用回调的原因记录在 errorDetails 中。如果模板私信随后也失败，条目为 failed，errorDetails 会给出发送错误，后接回调原因。请留意这一点：否则，每次派发都失败的回调看起来与正常工作的回调毫无二致。请确保你的 message 本身就可以发送。如果它对某个收件人渲染为空，例如在不携带用户名的私信触发器上只有 {{recipient_username}}，且你的回调文本未被使用，则不会发送任何私信，该动作为 failed，原因记录在 errorDetails 中。

Webhook 事件

两种事件会投递到你通过 POST /hook/webhook 注册的 automations Webhook 动作。两者都携带 type 字段——在读取其他任何内容之前，先根据它分支处理。

`type`	发送时机
`automation.triggered`	规则的 `fire_webhook` 动作运行时
`automation.completed`	派发完成时，附带其结果

automation.completed 默认关闭。在某条自动化的 fire_webhook 动作上设置 "sendCompletedEvent": true 即可为其开启。否则它保持关闭，因此按每次触发一个载荷构建的接收方仍会恰好收到一个载荷。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 而不是被省略，因此结构是稳定的。对于 dm_keyword、dm_reaction 和 story_reply，recipientUsername 为 null，因为 Meta 的载荷中不包含用户名。commentId 仅在 comment_keyword 和 story_comment 时设置，postId 仅在 comment_keyword 时设置，storyId 仅在动态类触发器时设置。story_reply 没有 keyword。对于 dm_keyword，commentText 是私信文本；对于 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。在最后一种情况下，某些动作可能已经运行过，因此私信可能已经发出，automation.triggered 也可能已经发送。 Webhook 投递是至少一次的，因此同一事件偶尔会到达两次，而被重试的派发可能会带着新的 hookId 再次发送 automation.triggered。切勿基于 hookId 去重。请对每种事件类型分别设置去重键，使处理其中一个绝不会抑制另一个：automation.completed 以 activityId 为键（每条活动只有一个结果），automation.triggered 以 activityId 加 actionId 为键（每个 fire_webhook 动作一个）。这两个事件是独立投递的，因此 automation.completed 偶尔会先于 automation.triggered 到达。

如果没有注册 Webhook

fire_webhook 会向该资料上注册的 automations 动作发送 POST 请求，并回退到你的 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 用户名（仅限评论触发器）。在私信和动态回复触发器中为空，在 Facebook 上始终为空
`{{recipient_id}}`	互动用户的 ID：在 Instagram 上为 Instagram 范围 ID（IGSID），在 Facebook 上为主页范围 ID（PSID）
`{{recipient_name}}`	保留占位符；在未来有充实数据源填充之前解析为空
`{{sender_username}}`	保留占位符；目前在所有平台上都解析为空
`{{sender_name}}`	保留占位符；目前在所有平台上都解析为空
`{{comment_text}}`	触发规则的评论 / 私信 / 动态回复的文本
`{{comment_id}}`	触发规则的评论 / 消息的平台 id
`{{comment_sent_at}}`	事件的 ISO 8601 时间戳（在可用时）
`{{matched_keyword}}`	匹配到的关键词（对于 `dm_reaction` 为表情字符串）
`{{platform}}`	平台标识：`instagram` 或 `facebook`
`{{trigger_type}}`	触发器类型（例如 `comment_keyword`）

没有 sender_email / recipient_email。 这些字段被有意地不公开——你的账单邮箱不应出现在发给陌生人的私信中，而且 Meta 在任何 IG Webhook 上都不会提供收件人的邮箱地址。避免这些占位符能防止意外泄露。

示例模板：

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

速率限制与上限

套餐	活跃自动化（每资料）	每日私信上限（每账户）
Launch & Business	10	1,000
Enterprise	50	5,000

活跃自动化上限按每个用户资料 计算，而不是按父账户计算。你账户下的每个资料都各自享有 Launch/Business 10 或 Enterprise 50 的额度，因此拥有多个资料的账户可以在每个资料上运行相应数量的自动化。它统计的是活跃自动化，并在 POST（创建）和 PUT 重新激活（active: false → true）时都会强制执行，两者都会返回错误码 470。需要为每个资料提高上限？请联系支持为你的账户提高。 每日私信上限按每个 Ayrshare 父账户计算，在你所有资料之间共享，并且有每个资料的子上限，避免某个繁忙的资料耗尽整个账户的额度。当达到私信上限时，活动条目会记录状态 rate_limited，并且不会发送私信。 消息会话上限同样适用。send_dm 需要该资料启用 Messaging 附加功能，并且它发送的每条私信都会计入该资料每月的会话上限，与你自己发送的私信相同。达到上限后，发往新收件人的 send_dm 不会被发送，活动条目会记录状态 failed，上限提示信息位于 actionResults[].errorDetails。由评论触发的私信（comment_keyword 和 story_comment）是例外：达到上限时它们仍会被发送，并且仍会被计数。单条自动化的结构上限：1–50 个触发器、1–50 个动作。 Instagram 本身对每个账户的私信设定了大约每小时 200 条的上限。引擎通过 20–60 秒的抖动来分散派发，从而保持在此上限之内。

活动状态

GET /automations/:id/activity 返回的每一行都包含顶层的 status，以及 actionResults[] 内每个动作的 status：

状态	含义
`pending`	刚刚写入；工作程序尚未开始处理
`in_flight`	工作程序当前正在派发
`sent`	至少一个动作被平台接受，且没有命中鉴权错误。对于 `send_dm`，这意味着 Meta 已接受该消息——并不代表收件人已收到（见下方说明）
`failed`	没有任何动作被接受，且至少一个动作被平台拒绝或无法运行（且没有命中鉴权错误）。原因位于 `actionResults[].errorDetails`
`auth_error`	该账户的 Instagram 或 Facebook 主页凭据或消息传递权限无法使用——例如访问令牌过期或被撤销、未选择 Facebook Page，或未为该资料激活 Messaging。私信不会被重试。针对单个收件人的投递失败会被记录为 `failed`，而不是记在这里
`rate_limited`	达到每日私信上限（套餐或每资料）；未发送私信
`deduplicated`	该动作在去重窗口内已向此收件人触发过
`skipped`	该自动化在派发前被抑制——它在扇出与派发之间变为非活跃或已被删除、没有配置任何动作，或者触发它的互动来自该自动化自己的账户——最常见的情况是评论了你自己的帖子。在最后这种情况下不会运行任何动作：没有私信（账户无法给自己发消息），也没有 `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 账户发出，还是从你的 Facebook 主页通过 Messenger 发出。自动化只记录这一接受结果，不跟踪投递情况。Instagram 不向任何 API 公开消息投递情况，收件人是否真的收到取决于其 Instagram 的 Message requests 设置，Ayrshare 无法读取或影响该设置。请参见自动化私信已发送但未送达。

错误码

API 返回两种形态的错误：

业务规则错误携带带编号的自动化 code（例如 { "action": "automation", "code": 469, ... }）。
验证错误——任何格式不正确的请求主体（缺失或非法字段、未知模板变量、无法识别的键）——都会作为单个 473 响应返回，附带一个列出问题字段的 details 对象。details 是校验器的输出（formErrors 加 fieldErrors）。请根据 details 分支处理，而不要根据逐条件的 code。在 fieldErrors 中，键对应请求的顶层字段（triggers、actions）：某条条目内部的问题，例如某个触发器缺少 keywords，会汇报到该字段（例如 triggers）之下，而 formErrors 保存的是对象层级的问题，例如无法识别的键。

代码	HTTP	含义
468	403	需要 Business 或 Enterprise 套餐
469	404	未找到自动化（当调用者不拥有该自动化时也会返回）
470	429	已达到你套餐等级的活跃自动化上限
471	400	该资料在请求的平台上未关联社交账户
472	403	你的账户尚不可使用此功能——请联系我们获取抢先体验
473	400	校验失败（请求主体格式错误）——请检查 `details`

Launch 套餐同样包含在内。 Business Launch 会归入 Business 等级，因此 Launch、Business 与 Enterprise 套餐均可使用自动化。468 仅会返回给不包含自动化的套餐。

Meta 不允许的内容

一些常被请求的功能因 Meta 在公共 Instagram API 上不允许而未被支持：

新粉丝自动私信。 Instagram 不发布关注类 Webhook。
给陌生人发送首条私信。 Meta 要求收件人必须先有过互动（评论、回复、私信、表情反应）之后，商家账户才能给对方发送消息。这里所支持的每一种触发器都锚定于这样的互动——但请注意，被允许发送并不等同于消息已被投递：收件人的 Instagram Message requests 设置仍然可能导致 Meta 接受消息后又将其静默丢弃（参见自动化私信已发送但未送达）。
批量对外营销活动。 每小时的私信上限与反滥用启发式规则在平台层面适用。

多资料使用

这些端点会遵循 profileKey 请求头。传入子资料的密钥后，自动化会在该资料下创建/管理。速率限制通过每资料子上限在各资料之间拆分，避免某个话痨资料耗尽父账户的额度。

常见问题

我可以在有新粉丝时触发吗？

不可以。Instagram 不发布关注类 Webhook，Meta 也不允许第三方应用向尚未先行互动的用户发送私信。所支持的每一种触发器（comment_keyword、story_reply、dm_reaction、dm_keyword）都锚定于这样的互动，正是这一点让发送成为被允许的。

为什么某条活动条目显示 sent，但收件人却从未收到私信？

sent 表示 Meta 接受了该消息，并不代表已投递。这对 Instagram 和 Facebook（从你的主页通过 Messenger 发送）都成立：自动化只记录接受结果，不跟踪投递情况。在 Instagram 上，投递取决于收件人的 Instagram Message requests 设置——如果他们不允许来自所有人的消息请求，Meta 会返回成功响应并静默丢弃该消息，任何 API 层面都不会有错误、Webhook 或其他信号。即便是投递成功的评论触发私信，也会作为收件人必须接受的消息请求送达（除非已存在会话）。这是 Instagram 平台的一项永久限制。请参见自动化私信已发送但未送达。

如果自动化触发时我的访问令牌无效怎么办？

如果账户的 Instagram 或 Facebook 主页凭据或消息传递权限确实失效——例如访问令牌过期或被撤销、未选择 Facebook Page，或未为该资料激活 Messaging——活动条目会记录状态 auth_error，并且私信不会被重试。修复账户状态后（重新关联、选择 Page 或激活 Messaging），下一次匹配到的互动就会正常触发。这只适用于真正的凭据与权限失败：如果某条特定的私信因其他原因未能投递——例如找不到收件人，或触发它的互动来自本会发送该私信的账户——该行会被记录为 failed 或 skipped，原因位于 actionResults[].errorDetails，重新关联并不会改变结果。

为什么发送私信前会有延迟？

每次派发都会在互动之后延迟 20–60 秒才被安排，以便 DM 发送在 Instagram 的反垃圾系统看来更像自然行为。该延迟在匹配任何规则之前就作用于互动本身，因此规则上的每个动作都会受到影响，包括 fire_webhook 和 send_email——你的 Webhook 会在评论后 20–60 秒到达，而不是立即到达。活动条目的 created 时间戳是触发匹配的时间；completedAt 是派发完成的时间。

活动条目会永久保留吗？

活动条目会无限期保留用于追踪和分析。为了性能考虑，GET /automations/:id/activity 端点返回近 30 天的条目。（去重保护使用自己的每动作窗口——默认为 7 天——它与活动回溯范围无关。）

删除自动化会移除其活动历史吗？

不会。删除是软删除：主记录被标记为 deleted，不会再产生新的派发，但历史活动条目仍可通过活动端点读取。

端点

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

工作原理

触发器

使用 `"all"` 的常青规则

Facebook 主页

动作

每个动作的去重窗口

动态消息内容

Webhook 事件

`automation.triggered`

`automation.completed`

如果没有注册 Webhook

模板变量

速率限制与上限

活动状态

错误码

Meta 不允许的内容

多资料使用

常见问题

端点

​工作原理

​触发器

​使用 "all" 的常青规则

​Facebook 主页

​动作

​每个动作的去重窗口

​动态消息内容

​Webhook 事件

​automation.triggered

​automation.completed

​如果没有注册 Webhook

​模板变量

​速率限制与上限

​活动状态

​错误码

​Meta 不允许的内容

​多资料使用

​常见问题

​端点

工作原理

触发器

使用 `"all"` 的常青规则

Facebook 主页

动作

每个动作的去重窗口

动态消息内容

Webhook 事件

`automation.triggered`

`automation.completed`

如果没有注册 Webhook

模板变量

速率限制与上限

活动状态

错误码

Meta 不允许的内容

多资料使用

常见问题

端点