> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 自动化 API 概述

> 由互动触发的 Instagram 自动化——当终端用户评论、回复动态、对私信做出表情反应或发送私信时，触发发送私信、Webhook 或电子邮件

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["business", "enterprise"]} maxPackRequired={false} />

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

自动化端点让你可以定义规则，自动响应传入的 Instagram 互动。每条自动化规则由一个或多个**触发器**（触发规则的事件）与一个或多个**动作**（触发时发生的操作）组成。一条规则可以监听多种触发器并派发多个动作——比如从同一次互动中同时向你的分析管线触发一个 Webhook，并发送一条私信。

引擎完全运行在 Meta 的政策框架内（不允许基于关注触发的私信、不允许向陌生人发送首条私信、不允许批量群发），并继承了 Ayrshare 的每账户速率限制、每收件人去重以及幂等 Webhook 接入。

## 工作原理

<Steps>
  <Step title="创建自动化">
    调用 `POST /automations`，附上你想要的触发器和动作。自动化会立即激活。
  </Step>

  <Step title="终端用户产生互动">
    有人在你的帖子上评论、回复你的动态、发送私信或对私信做出表情反应。Meta 会将 Webhook 投递给 Ayrshare。
  </Step>

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

  <Step title="查看触发情况">
    `GET /automations/:id/activity` 返回审计日志——每次派发尝试、每个动作的结果以及任何错误。
  </Step>
</Steps>

## 触发器

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

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

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

## 动作

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

| 类型             | 效果                                                                                            | 配置                                                  |
| -------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `send_dm`      | 使用[模板化消息](#template-variables)，向触发规则的用户发送 Instagram 私信。                                       | `message`（必填，支持模板）                                  |
| `fire_webhook` | 将自动化上下文以 POST 请求发送到你账户级别的 Webhook URL（通过 [`POST /hook/webhook`](/apis/webhooks/register) 配置）。 | *（无——载荷结构是固定的；见[下文](#fire_webhook-payload)）*        |
| `send_email`   | 通过平台的邮件管线排队发送邮件。                                                                              | `to`（必填，邮箱地址）；`subject`（可选，支持模板）；`message`（必填，支持模板） |

### 每个动作的去重窗口

每个动作——无论类型——还可以附加一个可选的顶层字段 `dedupWindowMinutes`，用于覆盖该动作的**默认 7 天**每收件人去重窗口。

* 设为 `0` 可**完全禁用**该动作的去重（通常用于 `fire_webhook` / `send_email`，因为接收方期望每个事件都收到）。
* 上限为 `525600`（一年）。

```json Action with a 24h dedup override theme={"system"}
{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}
```

### `fire_webhook` 载荷

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

```json theme={"system"}
{
  "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`）        |

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

示例模板：

```
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       |

活跃自动化上限按**每个 [用户资料](/apis/profiles/overview)** 计算，而不是按父账户计算。你账户下的每个资料都各自享有 Business 10 / Enterprise 50 的额度，因此拥有多个资料的账户可以在每个资料上运行相应数量的自动化。它统计的是活跃自动化，并在 `POST`（创建）和 `PUT` 重新激活（`active: false → true`）时都会强制执行，两者都会返回错误码 `470`。需要为每个资料提高上限？请[联系支持](mailto:support@ayrshare.com)为你的账户提高。

**每日私信上限**按每个 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` 请求头。传入子资料的密钥后，自动化会在该资料下创建/管理。速率限制通过每资料子上限在各资料之间拆分，避免某个话痨资料耗尽父账户的额度。

## 常见问题

<AccordionGroup>
  <Accordion title="我可以在有新粉丝时触发吗？">
    不可以。Instagram 不发布关注类 Webhook，Meta 也不允许第三方应用向尚未主动发起会话的用户发送私信。所支持的每一种触发器（`comment_keyword`、`story_reply`、`dm_reaction`、`dm_keyword`）都满足"用户先联系了你"的要求。
  </Accordion>

  <Accordion title="如果自动化触发时我的访问令牌无效怎么办？">
    活动条目会记录状态 `auth_error`，并且私信不会被重试。重新关联账户后，下一次匹配到的互动会正常触发。
  </Accordion>

  <Accordion title="为什么发送私信前会有延迟？">
    每次 `send_dm` 派发都会在互动之后延迟 20–60 秒才被安排发送，以便在 Instagram 的反垃圾系统看来更像自然行为。`fire_webhook` 和 `send_email` 动作则**没有**抖动延迟。活动条目的 `created` 时间戳是触发匹配的时间；`completedAt` 是派发完成的时间。
  </Accordion>

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

  <Accordion title="删除自动化会移除其活动历史吗？">
    不会。删除是软删除：主记录被标记为 `deleted`，不会再产生新的派发，但历史活动条目仍可通过活动端点读取。
  </Accordion>
</AccordionGroup>

## 端点

* [`POST /automations`](/apis/automations/create-automation) — 创建新的自动化
* [`GET /automations`](/apis/automations/list-automations) — 列出你的自动化
* [`GET /automations/:id`](/apis/automations/get-automation) — 获取某条自动化及其触发器与动作
* [`PUT /automations/:id`](/apis/automations/update-automation) — 部分更新；通过 `active: false` 暂停
* [`DELETE /automations/:id`](/apis/automations/delete-automation) — 软删除
* [`GET /automations/:id/activity`](/apis/automations/get-activity) — 分页游标形式的派发审计日志