自动化 API 概述 - Ayrshare API Documentation

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

自动化端点让你可以定义规则，自动响应传入的 Instagram 互动。每条自动化规则由一个或多个触发器（触发规则的事件）与一个或多个动作（触发时发生的操作）组成。一条规则可以监听多种触发器并派发多个动作——比如从同一次互动中同时向你的分析管线触发一个 Webhook，并发送一条私信。引擎完全运行在 Meta 的政策框架内（不允许基于关注触发的私信、不允许向陌生人发送首条私信、不允许批量群发），并继承了 Ayrshare 的每账户速率限制、每收件人去重以及幂等 Webhook 接入。

工作原理

创建自动化

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

终端用户产生互动

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

Ayrshare 匹配并派发

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

查看触发情况

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

触发器

一条自动化最多可关联 50 个触发器。每个触发器基于 type 字段的可辨联合类型；特定类型的字段位于同一层级。在 v1 中，所有触发器仅限 Instagram。

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

关键词匹配不区分大小写且按整词匹配。如果事件包含任一已配置的关键词，即满足带关键词过滤器的触发器。在动态触发器中省略 storyId 会对所连接账户的每一条动态都触发。

动作

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

类型	效果	配置
`send_dm`	使用模板化消息，向触发规则的用户发送 Instagram 私信。	`message`（必填，支持模板）
`fire_webhook`	将自动化上下文以 POST 请求发送到你账户级别的 Webhook URL（通过 `POST /hook/webhook` 配置）。	（无——载荷结构是固定的；见下文）
`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
}

`fire_webhook` 载荷

当 fire_webhook 运行时，会向你账户级别的 Webhook URL 发送一个 JSON 主体的 POST 请求：

{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "timestamp":         "2026-05-12T09:14:22.000Z"
}

当触发器未填充相应字段时（例如 dm_keyword 在 Meta 的载荷中不携带用户名；story_reply 没有关键词），recipientUsername 与 keyword 会是 null。

模板变量

send_dm.message、send_email.subject 和 send_email.message 支持 {{placeholder}} 替换。未知占位符会在创建/更新时被拒绝（作为 473 验证错误），因此拼写错误绝不会将字面 {{foo}} 静默泄露到面向用户的消息中。

占位符	解析为
`{{recipient_username}}`	互动用户的 Instagram 用户名（如果 Webhook 携带）
`{{recipient_id}}`	互动用户的 Instagram 参与者 ID（IGSID）
`{{recipient_name}}`	保留占位符；在未来有充实数据源填充之前解析为空
`{{sender_username}}`	你所关联的 Instagram 用户名
`{{sender_name}}`	你所关联的 Instagram 显示名
`{{comment_text}}`	触发规则的评论 / 私信 / 动态回复的文本
`{{comment_id}}`	触发规则的评论 / 消息的平台 id
`{{comment_sent_at}}`	事件的 ISO 8601 时间戳（在可用时）
`{{matched_keyword}}`	匹配到的关键词（对于 `dm_reaction` 为表情字符串）
`{{platform}}`	平台标识（例如 `instagram`）
`{{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

速率限制与上限

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

活跃自动化上限按每个用户资料 计算，而不是按父账户计算。你账户下的每个资料都各自享有 Business 10 / Enterprise 50 的额度，因此拥有多个资料的账户可以在每个资料上运行相应数量的自动化。它统计的是活跃自动化，并在 POST（创建）和 PUT 重新激活（active: false → true）时都会强制执行，两者都会返回错误码 470。需要为每个资料提高上限？请联系支持为你的账户提高。 每日私信上限按每个 Ayrshare 父账户计算，在你所有资料之间共享，并且有每个资料的子上限，避免某个繁忙的资料耗尽整个账户的额度。当达到私信上限时，活动条目会记录状态 rate_limited，并且不会发送私信。单条自动化的结构上限：1–50 个触发器、1–50 个动作。 Instagram 本身对每个账户的私信设定了大约每小时 200 条的上限。引擎通过 20–60 秒的抖动来分散派发，从而保持在此上限之内。

活动状态

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

状态	含义
`pending`	刚刚写入；工作程序尚未开始处理
`in_flight`	工作程序当前正在派发
`sent`	每个动作都成功
`failed`	至少一个动作失败（并且没有命中鉴权错误）
`auth_error`	Instagram 访问令牌无效；私信不会被重试
`rate_limited`	达到每日私信上限（套餐或每资料）；未发送私信
`deduplicated`	该动作在去重窗口内已向此收件人触发过
`skipped`	在扇出与派发之间，该自动化变为非活跃或已被删除

pending 与 in_flight 为过渡状态；其他都为终态。

错误码

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`

Meta 不允许的内容

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

新粉丝自动私信。 Instagram 不发布关注类 Webhook。
给陌生人发送首条私信。 Meta 要求收件人必须先主动联系（评论、回复、私信、表情反应）之后，商家账户才能给对方发送消息——而这里所支持的每一种触发器都正是这种情形。
批量对外营销活动。 每小时的私信上限与反滥用启发式规则在平台层面适用。

多资料使用

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

常见问题

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

不可以。Instagram 不发布关注类 Webhook，Meta 也不允许第三方应用向尚未主动发起会话的用户发送私信。所支持的每一种触发器（comment_keyword、story_reply、dm_reaction、dm_keyword）都满足”用户先联系了你”的要求。

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

活动条目会记录状态 auth_error，并且私信不会被重试。重新关联账户后，下一次匹配到的互动会正常触发。

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

每次 send_dm 派发都会在互动之后延迟 20–60 秒才被安排发送，以便在 Instagram 的反垃圾系统看来更像自然行为。fire_webhook 和 send_email 动作则没有抖动延迟。活动条目的 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 — 分页游标形式的派发审计日志

​工作原理

​触发器

​动作

​每个动作的去重窗口

​fire_webhook 载荷

​模板变量

​速率限制与上限

​活动状态

​错误码

​Meta 不允许的内容

​多资料使用

​常见问题

​端点

工作原理

触发器

动作

每个动作的去重窗口

`fire_webhook` 载荷

模板变量

速率限制与上限

活动状态

错误码

Meta 不允许的内容

多资料使用

常见问题

端点