自动化 API

自动化是由多个步骤组成的工作流：一个或多个启动它的触发器，随后是动作、条件、延迟、AI 步骤以及其他连接成图的组件。这与您在自动化页面中看到并编辑的自动化是同一个概念。本指南涵盖了如何通过 API 读取和构建这些自动化。

基础 URL：https://api.dmchamp.com/v1
身份验证：您的 API 密钥（请参阅身份验证）
错误：请参阅下方的错误与分页和错误

以下所有示例均展示了 cURL 中的 ?apiKey= 查询形式以及 JavaScript 和 Python 中的 X-API-Key 标头。两者在每个端点上均适用。

代理机构： 本页面上的每个端点都接受 sub_account_id 作为查询参数，因此您可以使用您的代理机构密钥读取和构建客户的自动化。如果 sub_account_id 不是您的客户账户之一，则会返回 404。请参阅代理机构 API。

工作原理：先创建草稿

该 API 的构建旨在确保没有任何内容会意外启动。

读取目录。 GET /automations/steps 列出了您可以使用的每种触发器、动作和步骤类型，以及编写图表的语法（graph_rules）。
创建草稿。 POST /automations 会在关闭状态下存储自动化。此时没有任何内容运行。
检查它。 读取它，在构建器中打开它（响应会为您提供其 open_path），并确保账户所有者已了解其功能及作用对象。
开启它。 POST /automations/{automationId}/enable 是一个单独的调用。这是使实际操作发生的步骤：发送消息、更改记录、为 AI 代理提供工具。

编辑操作永远不会改变自动化的开启或关闭状态。这也意味着对已开启的自动化所做的编辑会立即生效，作用于实时运行的自动化。若要安全地更改正在运行的自动化，请先禁用它，进行编辑和检查，然后再重新启用。

您发送的每个图表都会经过构建器画布所应用的相同检查。如果图表无法打开或运行，系统将拒绝该请求并返回一个 400，其中列出了需要修复的具体内容。

访问权限

账户需要具备“自动化”功能。如果没有该功能，本页面上的每个调用都会返回 403。
团队成员的访问权限遵循其在团队管理中“自动化”区域的设置：读取（列表、获取、步骤、运行、文件夹）需要查看权限，任何涉及更改的操作都需要编辑权限。
在其套餐不支持创建和编辑自动化的客户账户上，写入调用会返回 403，这与应用程序中构建器的表现一致。

自动化对象

列表返回每个自动化的摘要，不包含其步骤：

{
  "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
  "name": "Price question auto-reply",
  "description": "Replies with the price list when someone asks about prices.",
  "enabled": false,
  "updated_at": "2026-10-27T09:40:00.000Z",
  "trigger_kind": "incoming_message",
  "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708",
  "folder_name": "Sales"
}

字段	含义
`id`	自动化的 ID。
`name`	它在列表中的名称。
`description`	关于其功能的简短描述（一到三句话），或 `null`。
`enabled`	它是否已开启。已禁用的自动化永远不会运行。
`updated_at`	上次更改的时间。
`trigger_kind`	触发它的条件，例如 `incoming_message`、`schedule`、`webhook`、`agent_function` 或 `manual`。当图表尚未设置触发器时为 `null`。
`folder_id`, `folder_name`	它所在的文件夹，若未归档则为 `null`。

读取一个自动化流程会添加 created_at 及其 graph：

{
  "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
  "name": "Price question auto-reply",
  "description": "Replies with the price list when someone asks about prices.",
  "enabled": false,
  "created_at": "2026-10-27T09:12:00.000Z",
  "updated_at": "2026-10-27T09:40:00.000Z",
  "trigger_kind": "incoming_message",
  "folder_id": null,
  "folder_name": null,
  "graph": {
    "nodes": [
      {
        "id": "trigger_1",
        "kind": "trigger",
        "label": "Incoming message",
        "alias": "incoming_message",
        "action": "incoming_message",
        "params": { "message_filter_contains": "price" },
        "config": { "kind": "incoming_message", "message_filter_contains": "price" }
      },
      {
        "id": "send_prices",
        "kind": "action",
        "label": "Send message",
        "alias": "send_message",
        "action": "SEND_MESSAGE",
        "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" },
        "config": { "provider": "native", "slug": "SEND_MESSAGE", "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" } }
      }
    ],
    "edges": [{ "from": "trigger_1", "to": "send_prices" }]
  }
}

每个步骤 (nodes[]) 包含：

字段	含义
`id`	步骤的 id，在图中是唯一的。
`kind`	步骤的类型：`trigger`、`action`、`condition`、`transform`、`ai`、`delay`、`loop` 或 `respond`。请参阅步骤类型。
`label`	在构建器中步骤上显示的名称。
`alias`	步骤的引用名称。后续步骤将其输出读取为 `${nodes.<alias>.<field>}`。`null` 用于没有引用名称的步骤（此时通过其 id 引用）。
`action`	步骤的功能：它执行的操作，或者在触发步骤时为触发器类型。`null` 用于其他步骤。
`params`	操作步骤的参数，或触发步骤的设置。`null` 用于所有其他类型。为兼容旧版本保留：`config` 包含相同的值以及更多信息。
`config`	构建器存储的步骤完整设置，适用于所有类型的步骤：条件的规则、AI 步骤的提示词、延迟的时长、操作的标识符 (slug) 和参数。

每个连接 (edges[]) 都有 from 和 to（步骤 id），以及当它跟随步骤的某个分支时所对应的 branch，例如条件之后的 true 或 false。

在输出时，config 中的两项内容会发生变化：

隐藏密钥。 看起来像凭据的值（Webhook 密钥、令牌、API 密钥、密码、请求头值）将返回为 "[redacted]"。将 "[redacted]" 原样发回，即可保留已存储的值。
长文本会被截断。 超过约 4,000 个字符的单个文本会被截断并以省略号结尾。如果您要发回该步骤，请先填回其完整文本。

列出自动化流程

GET /automations 返回账户中的自动化流程，按最近修改时间排序（不包含步骤详情）。

查询参数（均为可选）：folder_id（仅限该文件夹中的自动化流程，使用列出文件夹中的 id，或使用 none 表示不在任何文件夹中的流程），sub_account_id。

cURL

curl "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY&folder_id=none"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/automations?folder_id=none", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { automations } = await res.json();

Python

res = requests.get(
    "https://api.dmchamp.com/v1/automations",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"folder_id": "none"},
)
automations = res.json()["automations"]

响应 (200)

{ "success": true, "automations": [{ "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "enabled": false, "...": "..." }] }

如果无法连接到自动化服务，您将收到 503，绝不会返回空列表。空列表始终表示没有任何自动化流程。

获取自动化流程

GET /automations/{automationId} 返回一个包含完整图结构的自动化流程：每个步骤的类型、标签、别名、操作、参数和设置，以及它们之间的连接。

curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { automation } = await res.json();

res = requests.get(
    "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
automation = res.json()["automation"]

响应 (200)

{ "success": true, "automation": { "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "graph": { "nodes": ["..."], "edges": ["..."] } } }

如果 id 不属于此账户，则返回 404。

步骤目录

GET /automations/steps 返回构建自动化流程所需的一切组件：

node_kinds：8 种步骤类型，每种都有标签和描述。
triggers：所有可以启动自动化的触发器，包含其设置字段（fields）以及它传递给后续步骤的值（output_keys）。
actions：动作步骤可以运行的内置动作，每个动作都有其 key（你在图表中使用的标识符）及其 params，并标记了它们所在的 required。
api_actions：动作步骤可以调用的此 API 的操作。如果没有 q，它们将作为按区域分组的标签返回在 api_actions_by_tag 中，而扁平列表为空，因为它们有数百个。
graph_rules：编写图表的语法：每种步骤类型携带的数据、每种触发器及其设置键、动作提供程序、分支名称和模板语法。在创建或编辑图表之前请阅读它。
counts：每个列表的总数，无论你搜索的是什么。

这是构建器提供的功能，而不是账户已经构建的内容。在断定某个触发器或动作不存在之前，请先检查此项。

查询参数（均为可选）：q，用于在每个列表中搜索的词（不区分大小写），以及 sub_account_id。

使用 q 时：

api_actions 是匹配项的扁平列表，上限为 60 个。api_actions_truncated 是应用上限时的 true。前几个匹配项带有其参数。
已连接的第三方应用的动作也会被搜索，并返回在 app_actions 中。按应用名称搜索，例如 q=hubspot。每个条目都会说明账户是否已连接该应用（connected），connected_apps 列出了账户已连接的应用。
如果此次无法搜索应用动作，app_actions_unavailable 将为 true。其他列表仍然完整。

curl "https://api.dmchamp.com/v1/automations/steps?apiKey=YOUR_API_KEY&q=tag"

const res = await fetch("https://api.dmchamp.com/v1/automations/steps?q=tag", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { triggers, actions, graph_rules } = await res.json();

res = requests.get(
    "https://api.dmchamp.com/v1/automations/steps",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"q": "tag"},
)
catalogue = res.json()

响应（200，已缩短）

{
  "success": true,
  "q": "tag",
  "node_kinds": [{ "kind": "trigger", "label": "Trigger", "description": "Starts the automation when an event happens." }],
  "triggers": [
    {
      "kind": "tag_applied",
      "label": "Tag applied",
      "group": "Contacts",
      "fields": ["tag_name", "channel", "applied_by"],
      "output_keys": ["contact.id", "contact.first_name", "..."]
    }
  ],
  "actions": [
    {
      "key": "SET_CONTACT_TAG",
      "label": "Set contact tag",
      "group": "Contacts",
      "provider": "native",
      "params": [{ "key": "contact_id", "required": true }, { "key": "tag", "required": true }]
    }
  ],
  "api_actions": ["..."],
  "app_actions": [],
  "graph_rules": "GRAPH: { nodes: [{ id, type, label?, data }], edges: [{ source, target, sourceHandle? }] } ...",
  "counts": { "node_kinds": 8, "triggers": 40, "actions": 44, "api_actions": 454 }
}

下方的步骤类型和触发器列表取自此端点。端点本身始终是当前列表。

创建自动化

POST /automations 通过名称和图表创建自动化。它被存储为关闭状态，即草稿。

请求体

字段	必填	含义
`name`	是	它在列表中的名称。简短且具体。
`description`	否	关于它做什么以及何时运行的一到三句话描述。
`graph`	是	`{ nodes, edges }`，见下文。
`folder_id`	否	存放它的文件夹，来自列出文件夹的 ID。如果省略或为 `null`，则不放入任何文件夹。

图表。 来自步骤目录的 graph_rules 是完整的语法。简而言之：

每个节点都有一个 id（在图表中唯一，例如 trigger_1 或 send_reminder）、一个 type（8 种步骤类型之一）、一个可选的 label，以及其在 data 中的设置，位于以其类型命名的键下：data.trigger = { kind, ... }、data.action = { provider, slug, params }、data.condition = { ... }、data.delay = { seconds }、data.ai = { prompt }、data.loop = { over }、data.transform = { language, code }、data.respond = { status, body, content_type }。
自动化至少需要一个触发器。实时语法允许最多 10 个，当其中任何一个触发时，自动化就会开始。
其他每个步骤都必须能从触发器到达，且没有任何连接可以指向之前的步骤。
每条边都有一个 source 和一个 target。离开条件的边带有 sourceHandle true 或 false。离开循环的边带有 body 或 done。离开“等待回复”延迟的边带有 replied 或 timed_out。其他边没有 sourceHandle；语法列出了其余部分。
动作标识符和参数来自目录。永远不要猜测 ID（代理、标签、列表、阶段）：请先通过 API 查找它，或者将该字段留空为 ""，以便用户在构建器中选择。
位置是可选的。没有位置的步骤会自动布局。
来自之前步骤的值写为 ${trigger.<field>} 和 ${nodes.<step>.<field>}。请参阅自动化指南中的使用之前步骤返回的内容和表达式。

图表接受两种拼写方式：构建器自己的（节点带有 type 和 data，边带有 source 和 target，如下所示）以及获取自动化返回的格式（节点带有 kind、config、action、params；边带有 from、to、branch）。因此，你可以读取一个自动化，更改一个步骤，然后将其发回。

curl -X POST "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price question auto-reply",
    "description": "Replies with the price list when someone asks about prices.",
    "graph": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger", "label": "Incoming message",
          "data": { "trigger": { "kind": "incoming_message", "message_filter_contains": "price" } } },
        { "id": "send_prices", "type": "action", "label": "Send message",
          "data": { "action": { "provider": "native", "slug": "SEND_MESSAGE",
            "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" } } } }
      ],
      "edges": [{ "source": "trigger_1", "target": "send_prices" }]
    }
  }'

const res = await fetch("https://api.dmchamp.com/v1/automations", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Price question auto-reply", graph: { nodes, edges } }),
});
const { automation, draft, open_path, warnings } = await res.json();

res = requests.post(
    "https://api.dmchamp.com/v1/automations",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Price question auto-reply", "graph": {"nodes": nodes, "edges": edges}},
)
draft = res.json()

响应 (201)

{
  "success": true,
  "automation": { "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "enabled": false, "graph": { "...": "..." } },
  "draft": true,
  "open_path": "/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f",
  "warnings": []
}

automation 是存储的自动化，形状与获取自动化相同。
当它被关闭时，draft 为 true。新的自动化在启用之前始终是草稿，因此这里的 enabled: false 是正常的，并非失败。
open_path 是它在应用构建器中打开的位置。
warnings 列出了构建器无法完成的内容，以短标签形式显示（例如 agent_function:not_linked）。当一切正常时，它为空。

创建操作不能盲目重复。如果请求超时，请在再次发送之前列出您的自动化流程，否则您最终可能会得到两个草稿。

更新自动化流程

PUT /automations/{automationId} 用于更改名称、描述和/或图表。仅发送您想要更改的字段即可。

请求体：name、description、graph（均为可选，至少包含一个）。

graph 会替换整个图表，因此请务必基于已存储的内容进行操作：

使用 GET /automations/{automationId} 读取自动化流程。
在该图表中进行必要的更改。
将整个图表发回，包括所有步骤。

当您将其发回时：

保持每个步骤的 alias 与您获取时完全一致。 后续步骤通过别名（${nodes.<alias>.<field>}）引用该步骤。如果更改或删除它，对该步骤的所有引用都将失效。请参阅命名您的步骤。
保持 "[redacted]" 的值不变。 显示为 "[redacted]" 的值将保留其存储的值。
恢复被截断的文本。 读取时以省略号结尾的文本在读取过程中已被截断。

自动化流程的开启状态在此处不会被更改。如果它处于开启状态，您的编辑在保存后会立即生效。当自动化流程开启时，如果更改会导致其自我触发，则会被拒绝：请先将其禁用。

curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Price question auto-reply (EN)" }'

// Read, edit, send back the whole graph
const get = await fetch(`https://api.dmchamp.com/v1/automations/${id}`, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const { automation } = await get.json();
const step = automation.graph.nodes.find((n) => n.id === "send_prices");
step.config.params.body = "Hi ${trigger.contact.first_name}, our new price list: https://example.com/prices";
await fetch(`https://api.dmchamp.com/v1/automations/${id}`, {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ graph: automation.graph }),
});

url = f"https://api.dmchamp.com/v1/automations/{automation_id}"
automation = requests.get(url, headers={"X-API-Key": "YOUR_API_KEY"}).json()["automation"]
# ...edit automation["graph"] here, keeping every alias...
requests.put(url, headers={"X-API-Key": "YOUR_API_KEY"}, json={"graph": automation["graph"]})

响应 (200)：与创建操作格式相同（automation、draft、open_path、warnings）。如果不发送 name、description 或 graph 中的任何内容，将返回 400。

启用和禁用

POST /automations/{automationId}/enable 用于开启自动化流程，使其从现在起根据触发器运行。请仅在账户所有者了解自动化流程的功能及影响对象，并同意开启后才调用此接口。如果图表无法运行（例如没有触发器、存在循环、步骤自我触发），构建器将拒绝开启，并返回说明原因的 400。

POST /automations/{automationId}/disable 用于将其关闭（暂停）。已在运行中的任务会完成；不会启动新的运行。禁用操作始终是被允许的。

这两个调用都不需要请求体。

curl -X POST "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable?apiKey=YOUR_API_KEY"

await fetch("https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/disable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});

requests.post(
    "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

响应 (200)：当前存储的自动化流程，格式与创建操作相同，启用后包含 draft: false。

运行历史

GET /automations/{automationId}/runs 返回一个自动化的运行记录，按时间从新到旧排序：记录了每次运行的开始和结束时间、触发原因、是否成功，以及失败时的错误信息。阅读自动化配置可以了解它将要做什么。而运行历史则告诉你它实际做了什么，这是区分“从未运行过的自动化”与“每次运行都失败的自动化”的唯一方法。

查询参数（均为可选）：limit（1 到 50，默认为 10），sub_account_id。

curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?apiKey=YOUR_API_KEY&limit=20"

const res = await fetch("https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { runs, note } = await res.json();

res = requests.get(
    "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 20},
)
runs = res.json()["runs"]

响应 (200)

{
  "success": true,
  "automation": { "id": "8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f", "name": "Price question auto-reply", "enabled": true, "trigger_kind": "incoming_message" },
  "runs": [
    {
      "id": "run_7f3a",
      "status": "failed",
      "trigger_source": "incoming_message",
      "started_at": "2026-10-27T10:02:11.000Z",
      "finished_at": "2026-10-27T10:02:12.000Z",
      "error": "Contact is on Do Not Disturb list",
      "cancel_reason": null,
      "mode": "live"
    }
  ]
}

mode 对于真实运行为 live，对于编辑器中的 安全运行 (Safe run) 则为 safe。安全运行不会发送任何数据，因此不能证明自动化在实际使用中有效。
空的 runs 列表是一个有效的响应，而非缺失数据。此时响应中会包含一个 note：这表示触发器从未触发，或者自动化处于关闭状态，因此没有任何运行记录。

文件夹

文件夹仅用于在列表中对自动化进行分组。它们不会改变自动化的行为或其启用状态。请参阅在文件夹中组织自动化。

列出文件夹

GET /automations/folders 返回所有文件夹，每个文件夹包含其中包含的自动化数量，以及 unfiled_count：即未归入任何文件夹的自动化数量。

curl "https://api.dmchamp.com/v1/automations/folders?apiKey=YOUR_API_KEY"

{
  "success": true,
  "folders": [{ "id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708", "name": "Sales", "automation_count": 3 }],
  "unfiled_count": 5
}

创建文件夹

POST /automations/folders 使用 { "name": "Appointment reminders" }。名称为必填项，最多 100 个字符，且在账户内必须唯一。你可以通过移动自动化将自动化放入文件夹，或者在创建自动化时传入 folder_id。

curl -X POST "https://api.dmchamp.com/v1/automations/folders?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Appointment reminders" }'

响应 (201)：{ "success": true, "folder": { "id": "...", "name": "Appointment reminders", "automation_count": 0 } }。如果名称已被其他文件夹占用，则返回 409 以及 code: "folder_name_taken"。

重命名文件夹

PUT /automations/folders/{folderId} 使用 { "name": "..." }。其中的自动化将保持在原位。

响应 (200)：{ "success": true, "folder": { ... } }。

删除文件夹

DELETE /automations/folders/{folderId} 仅删除该文件夹。其中的自动化流程不会被删除：它们会移出文件夹，并像往常一样继续运行。

curl -X DELETE "https://api.dmchamp.com/v1/automations/folders/f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708?apiKey=YOUR_API_KEY"

{ "success": true, "deleted": true, "moved_to_no_folder": 3, "message": "Folder deleted. 3 automations were moved to No folder; no automation was deleted." }

将自动化流程移动到文件夹

PUT /automations/{automationId}/folder 使用 { "folder_id": "<folder id>" }，或者 { "folder_id": null } 将其移出文件夹。必须提供 folder_id。仅自动化流程的列表位置会发生改变。

curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/folder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708" }'

响应 (200)：{ "success": true, "automation_id": "...", "folder_id": "..." }。

类型	功能
`trigger`	当发生某事时启动自动化流程。
`action`	运行一个步骤：内置操作、API 操作、已连接应用的操作、HTTP 请求或电子邮件。
`condition`	根据规则拆分流程，分为 `true` 和 `false` 分支。
`transform`	运行一小段代码以在步骤之间重塑数据。
`ai`	使用您编写的提示词询问 AI。它可以返回文本、分离字段或从多个分支中选择一个。
`delay`	等待设定的时间，或等待联系人回复（带超时设置）。
`loop`	对列表中的每一项重复执行其中的步骤。
`respond`	向触发运行的 Webhook 调用或 AI 代理函数调用返回响应。

触发器

这些是目录目前列出的 40 个触发器，按构建器中的分组方式进行分类。设置列包含触发器自身的设置键 (fields)，用于缩小触发范围。每个触发器还接受 respect_quiet_hours、run_hours、reentry 和 stop_on_response；请参阅自动化设置。

消息传递

触发器 (`kind`)	触发条件	设置
收到消息 (`incoming_message`)	联系人在任何渠道发送消息。	`campaign`（限制为一个 AI 代理）、`channel`、`message_filter_contains`（关键词）、`message_filter_regex`（模式）
未接来电 (`missed_call`)	有人拨打您的 WhatsApp Web 号码或您的个人短信号码且无人接听。	`to_number`
消息已送达 (`message_delivered`)	您发送的消息被渠道确认送达。	`channel`、`agent`
消息发送失败 (`message_failed`)	您发送的消息无法送达，并附带错误信息。	`channel`、`agent`
消息已发送 (`message_sent`)	任何离开您账户的消息：AI 的、您的、广播或后续跟进。请进行过滤，否则它会在所有消息上运行。	`channel`、`sent_by`
已发送后续跟进 (`follow_up_sent`)	自动后续跟进已发出。	无
已跳过后续跟进 (`follow_up_skipped`)	因发送条件未满足而未发送后续跟进。	无
后续跟进已完成 (`follow_up_exhausted`)	联系人收到了序列中的最后一条后续跟进，且没有更多排队内容。	无
对话已关闭 (`conversation_closed`)	聊天已关闭，包含结束方式和摘要。	`channel`、`agent`
广播已完成 (`broadcast_completed`)	广播发送完毕，包含发送数量和失败数量。	无
线索回复已分类 (`outreach_reply_labelled`)	冷邮件线索的回复已分类，例如标记为“感兴趣”。	`label`
收到 Skool 评论 (`skool_comment_received`)	成员在您评论规则监控的 Skool 帖子下发表评论。	无

联系人

触发器 (`kind`)	触发条件	设置
新联系人 (`contact_created`)	新人首次通过任何渠道联系您，也适用于导入、API 和您手动创建的联系人。	无
联系人已更新 (`contact_updated`)	联系人字段发生变化。	`field`
您在此处添加的联系人 (`contact_added`)	仅适用于您从“联系人”页面手动放入此自动化流程的联系人。每个联系人运行一次。	无
标签已添加 (`tag_applied`)	标签被您的 AI 代理、人员、自动化流程或导入操作添加到联系人。	`tag_name`、`channel`、`applied_by`
标签已移除 (`tag_removed`)	标签从联系人身上移除。	`tag_name`、`channel`
Skool 成员加入 (`skool_member_joined`)	有人加入您拥有或管理的 Skool 社区，包含其个人资料、回答和匹配分数。	`group_id`、`create_contact`
Skool 成员已合格 (`skool_member_qualified`)	新 Skool 成员的回答分数达到或超过您的阈值。	`min_score`

交易

触发器 (`kind`)	触发条件	设置
交易已创建 (`deal_created`)	新交易被添加到您的某个管道中。	`pipeline_id`、`stage_id`
交易阶段已更改 (`deal_stage_changed`)	交易移动到不同阶段，标明离开的阶段和进入的阶段。	`pipeline_id`、`to_stage_id`、`from_stage_id`
交易已更新 (`deal_updated`)	交易字段发生变化。	`field`

预约

触发器 (`kind`)	触发条件	设置
预约已预订 (`appointment_booked`)	新预约已预订。	无
预约已取消 (`appointment_cancelled`)	已预订的预约被取消。	无
预约已改期 (`appointment_rescheduled`)	已预订的预约移动到其他时间，显示旧时间和新时间。	`event_id`
预约前 (`appointment_upcoming`)	在每次确认的预约前设定的时间，用于提醒。每个自动化流程最多五个提醒。	`offsets_minutes`

任务

触发器 (`kind`)	触发条件	设置
任务已创建 (`task_created`)	任务已创建。	`task_type`
任务已完成 (`task_completed`)	任务被移动到已完成阶段。	无

账户

触发器 (`kind`)	触发条件	设置
信用余额不足 (`low_credit_balance`)	您的信用余额低于警报阈值。	无
渠道已连接 (`channel_connected`)	您的某个渠道完成连接。	`channel`
渠道已断开 (`channel_disconnected`)	您的某个渠道掉线：已登出、取消关联或被切断。自动重新连接的 WhatsApp Web 号码仅在 30 分钟后仍处于断开状态时才计入。	`channel`

代理机构

触发器 (`kind`)	触发条件	设置
子账户已创建 (`sub_account_created`)	从您的仪表板、API 或注册页面创建了新的客户账户。	无
子账户活动 (`sub_account_event`)	您的某个客户账户发生变动：信用额度不足、渠道连接、计划变更。	`event`、`threshold`

常规与应用

触发器 (`kind`)	触发条件	设置
按计划 (`schedule`)	按 cron 计划执行。	`cron`, `timezone`
Webhook (`webhook`)	外部系统调用自动化的 Webhook 地址。	`webhook_secret`
AI 智能体函数 (`agent_function`)	您的 AI 智能体在对话期间将此自动化作为函数调用。	`function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids`
新订阅源项目 (`rss`)	RSS 或 Atom 订阅源中出现新项目。	`feed_url`
收到电子邮件 (`email_received`)	您的已连接邮箱收到一封电子邮件。	`from_contains`, `subject_contains`
应用事件 (`app_event`)	已连接的应用中发生了某些情况：交易阶段变更、收到付款、提交了表单等。	`toolkit`, `trigger_slug`, `connected_account_id`, `config`
手动运行 (`manual`)	仅在手动启动时触发。	无

每个自动化最多可以包含 webhook、app_event、agent_function、rss、schedule、email_received、appointment_upcoming 和 contact_added 各一个触发器。在记录创建时触发的触发器不能与创建相同记录的操作配对，因为这会导致自动化自我触发。

关于每个触发器传递给后续步骤的内容 (output_keys) 以及包含参数的操作完整列表，请阅读 GET /automations/steps。自动化指南以构建器的视角解释了每个触发器。

错误

每个错误都具有通常的 { "success": false, "error_code": <status>, "error": "..." } 格式。被拒绝的图表会添加 code 和 errors：

{
  "success": false,
  "error_code": 400,
  "code": "invalid_graph",
  "error": "<the first problem, as one sentence>",
  "errors": ["<the first problem, as one sentence>", "<the next problem>"]
}

errors 列出了每个问题，每个问题用一个可修复的句子描述，error 是第一个问题。请修复所列出的确切内容并重新发送整个图表。code 是 invalid_graph、automation_graph_has_a_cycle、self_triggering_automation、no_trigger 或来自构建器的其他代码之一。

状态	时间
`400`	图表被拒绝（见上文），缺少必填字段（创建时为 `name` 或 `graph`，移动时为 `folder_id`），更新未发送任何更改内容，自动化或文件夹 ID 无效，或者文件夹名称缺失、为空或过长 (`code: "invalid_name"`)。
`403`	账户没有自动化功能；客户账户的套餐不包含创建和编辑自动化（仅限写入）；或者团队成员的自动化访问权限过低（查看权限仅限读取，编辑权限支持写入）。
`404`	此账户中没有该 ID 的自动化，没有该 ID 的文件夹 (`code: "folder_not_found"`)，或者 `sub_account_id` 不是您的客户账户之一。
`409`	同名文件夹已存在 (`code: "folder_name_taken"`)。
`413`	自动化大小超过了构建器允许的 1 MB。请将大型代码或数据移出其步骤。
`422`	构建器因其他原因拒绝了请求。请根据 `GET /automations/steps` 检查图表；再次发送相同的请求无济于事。
`503`	无法连接到自动化服务。请稍后再试。对于创建操作，请先列出您的自动化，以免创建第二个草稿。

通过 MCP 使用这些端点

此页面上的每个端点也是您通过 MCP 连接的 AI 助手的工具，遵循相同的规则：新的自动化在启用前为草稿，对正在运行的自动化进行的编辑会立即生效。

工具	端点
`list_automations`	`GET /automations`
`get_automation`	`GET /automations/{automationId}`
`list_automation_steps`	`GET /automations/steps`
`create_automation`	`POST /automations`
`update_automation`	`PUT /automations/{automationId}`
`enable_automation`	`POST /automations/{automationId}/enable`
`disable_automation`	`POST /automations/{automationId}/disable`
`list_automation_runs`	`GET /automations/{automationId}/runs`
`list_automation_folders`	`GET /automations/folders`
`create_automation_folder`	`POST /automations/folders`
`rename_automation_folder`	`PUT /automations/folders/{folderId}`
`delete_automation_folder`	`DELETE /automations/folders/{folderId}`
`move_automation_to_folder`	`PUT /automations/{automationId}/folder`

后续步骤

自动化：触发器、步骤、变量和运行历史在构建器中是如何工作的。
代理 API：使用 sub_account_id 在客户账户上构建自动化。
API 参考：完整的交互式端点浏览器。

自动化 API #

工作原理：先创建草稿 #

访问权限 #

自动化对象 #

列出自动化流程 #

获取自动化流程 #

步骤目录 #

创建自动化 #

更新自动化流程 #

启用和禁用 #

运行历史 #

文件夹 #

列出文件夹 #

创建文件夹 #

重命名文件夹 #

删除文件夹 #

将自动化流程移动到文件夹 #

目录 #

步骤类型 #

触发器 #

错误 #

通过 MCP 使用这些端点 #

后续步骤 #

自动化 API

工作原理：先创建草稿

访问权限

自动化对象

列出自动化流程

获取自动化流程

步骤目录

创建自动化

更新自动化流程

启用和禁用

运行历史

文件夹

列出文件夹

创建文件夹

重命名文件夹

删除文件夹

将自动化流程移动到文件夹

目录

步骤类型

触发器

错误

通过 MCP 使用这些端点

后续步骤