API Tự động hóa #

Tự động hóa là một quy trình làm việc bao gồm các bước: một hoặc nhiều trình kích hoạt để bắt đầu, sau đó là các hành động, điều kiện, độ trễ, các bước AI và những thành phần khác, được kết nối thành một biểu đồ. Đây chính là quy trình tự động hóa mà bạn thấy và chỉnh sửa trên trang Tự động hóa. Hướng dẫn này bao gồm cách đọc và xây dựng chúng thông qua API.

• URL cơ sở: https://api.dmchamp.com/v1
• Xác thực: khóa API của bạn (xem Xác thực)
• Lỗi: xem Lỗi & Phân trang và Lỗi bên dưới

Tất cả các ví dụ bên dưới đều hiển thị dạng truy vấn ?apiKey= trong cURL và tiêu đề X-API-Key trong JavaScript và Python. Bạn có thể sử dụng cách nào cũng được cho mọi điểm cuối.

Đại lý: mọi điểm cuối trên trang này đều chấp nhận sub_account_id làm tham số truy vấn, vì vậy bạn có thể đọc và xây dựng các quy trình tự động hóa của khách hàng bằng khóa đại lý của mình. Một sub_account_id không thuộc tài khoản khách hàng của bạn sẽ trả về 404. Xem API cho Đại lý.

Cách thức hoạt động: bản nháp trước #

API được xây dựng để đảm bảo không có gì bắt đầu chạy ngoài ý muốn.

1. Đọc danh mục. GET /automations/steps liệt kê mọi trình kích hoạt, hành động và loại bước bạn có thể sử dụng, cùng với cú pháp để viết biểu đồ (graph_rules).
2. Tạo bản nháp. POST /automations lưu trữ quy trình tự động hóa ở trạng thái đã tắt. Chưa có gì chạy cả.
3. Kiểm tra. Đọc lại, mở nó trong trình xây dựng (phản hồi sẽ cung cấp cho bạn open_path của nó) và đảm bảo chủ sở hữu tài khoản đã xem quy trình đó làm gì và cho ai.
4. Bật nó lên. POST /automations/{automationId}/enable là một lệnh gọi riêng. Đây là bước làm cho mọi thứ thực sự xảy ra: tin nhắn được gửi đi, bản ghi được thay đổi, công cụ được cung cấp cho tác nhân AI.

Việc chỉnh sửa không bao giờ làm thay đổi trạng thái bật hay tắt của quy trình tự động hóa. Điều đó cũng có nghĩa là một chỉnh sửa đối với quy trình tự động hóa đang bật sẽ có hiệu lực ngay lập tức trên quy trình đang chạy. Để thay đổi một quy trình tự động hóa đang chạy một cách an toàn, hãy tắt nó, chỉnh sửa, kiểm tra và bật lại.

Mọi biểu đồ bạn gửi đều trải qua các bước kiểm tra giống như trình xây dựng áp dụng. Một biểu đồ không thể mở hoặc chạy sẽ bị từ chối với 400 liệt kê chính xác những gì cần sửa.

Quyền truy cập #

• Tài khoản cần có Tự động hóa. Nếu không, mọi lệnh gọi trên trang này sẽ trả về 403.
• Quyền truy cập của thành viên nhóm tuân theo khu vực Tự động hóa của họ trong Quản lý nhóm: việc đọc (danh sách, lấy, các bước, lượt chạy, thư mục) cần quyền Xem, mọi thứ làm thay đổi dữ liệu cần quyền Chỉnh sửa.
• Trên tài khoản khách hàng có gói không bao gồm việc tạo và chỉnh sửa tự động hóa, các lệnh gọi ghi sẽ trả về 403, giống hệt như cách trình xây dựng thực hiện trong ứng dụng.

Đối tượng tự động hóa #

Danh sách trả về bản tóm tắt của từng quy trình tự động hóa, không bao gồm các bước của nó:

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

Đọc một quy trình tự động hóa sẽ thêm created_at và graph của nó:

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

Mỗi bước (nodes[]) bao gồm:

Mỗi kết nối (edges[]) có from và to (ID của các bước), và branch khi nó theo một nhánh của bước, ví dụ true hoặc false sau một điều kiện.

Hai thứ trong config bị thay đổi khi xuất ra:

• Các bí mật bị ẩn. Các giá trị trông giống như thông tin xác thực (bí mật webhook, mã thông báo, khóa API, mật khẩu, giá trị tiêu đề) sẽ trả về dưới dạng "[redacted]". Gửi "[redacted]" trở lại mà không thay đổi thì giá trị đã lưu sẽ được giữ nguyên.
• Các văn bản dài bị rút ngắn. Một văn bản đơn lẻ dài hơn khoảng 4.000 ký tự sẽ bị cắt ngắn và kết thúc bằng dấu ba chấm. Nếu bạn gửi lại bước đó, hãy đặt lại toàn bộ văn bản của nó vào trước.

Liệt kê các quy trình tự động hóa #

GET /automations trả về các quy trình tự động hóa trên tài khoản, các quy trình được thay đổi gần đây nhất sẽ hiển thị trước, dưới dạng tóm tắt (không bao gồm các bước).

Tham số truy vấn (tất cả đều tùy chọn): folder_id (chỉ các quy trình tự động hóa trong thư mục đó, một ID từ Liệt kê thư mục, hoặc none cho các quy trình không nằm trong thư mục nào), 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"]

Phản hồi (200)

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

Nếu không thể kết nối với dịch vụ tự động hóa, bạn sẽ nhận được 503, thay vì một danh sách trống. Danh sách trống luôn có nghĩa là không có quy trình tự động hóa nào.

Lấy một quy trình tự động hóa #

GET /automations/{automationId} trả về một quy trình tự động hóa với biểu đồ đầy đủ của nó: loại, nhãn, bí danh, hành động, tham số và cài đặt của mọi bước, cộng với các kết nối giữa chúng.

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

Phản hồi (200)

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

Một ID không có trên tài khoản này sẽ trả về 404.

Danh mục bước #

GET /automations/steps trả về mọi thứ có thể dùng để xây dựng một quy trình tự động hóa:

• node_kinds: 8 loại bước, mỗi loại có nhãn và mô tả.
• triggers: mọi trình kích hoạt có thể bắt đầu một tự động hóa, cùng với các trường cài đặt (fields) và các giá trị mà nó cung cấp cho các bước sau (output_keys).
• actions: các hành động tích hợp sẵn mà một bước hành động có thể chạy, mỗi hành động có key (slug bạn sử dụng trong biểu đồ) và params, được đánh dấu required tại vị trí của chúng.
• api_actions: các thao tác của API này mà một bước hành động có thể gọi. Nếu không có q, chúng sẽ trả về dưới dạng các nhãn được nhóm theo khu vực trong api_actions_by_tag, và danh sách phẳng sẽ trống vì có hàng trăm thao tác như vậy.
• graph_rules: ngữ pháp để viết một biểu đồ: dữ liệu mà mỗi loại bước mang theo, mọi loại trình kích hoạt với các khóa cài đặt của nó, các nhà cung cấp hành động, tên nhánh và cú pháp mẫu. Hãy đọc kỹ trước khi bạn tạo hoặc chỉnh sửa biểu đồ.
• counts: tổng số lượng cho mỗi danh sách, bất kể bạn đã tìm kiếm gì.

Đây là những gì trình xây dựng cung cấp, không phải những gì tài khoản đã xây dựng. Hãy kiểm tra nó trước khi bạn kết luận rằng một trình kích hoạt hoặc hành động không tồn tại.

Tham số truy vấn (tất cả đều tùy chọn): q, một từ để tìm kiếm trong mọi danh sách (không phân biệt chữ hoa chữ thường), và sub_account_id.

Với q:

• api_actions là danh sách phẳng các kết quả khớp, giới hạn ở mức 60. api_actions_truncated là true khi áp dụng giới hạn. Các kết quả khớp đầu tiên mang theo các tham số của chúng.
• Các hành động cho ứng dụng bên thứ ba được kết nối cũng được tìm kiếm và trả về trong app_actions. Tìm kiếm theo tên ứng dụng, ví dụ q=hubspot. Mỗi hành động cho biết liệu tài khoản đã kết nối ứng dụng đó hay chưa (connected), và connected_apps liệt kê các ứng dụng mà tài khoản đã kết nối.
• app_actions_unavailable là true khi các hành động ứng dụng không thể tìm kiếm được vào lúc này. Các danh sách khác vẫn đầy đủ.

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()

Phản hồi (200, đã rút gọn)

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

Các danh sách loại bước và trình kích hoạt bên dưới được lấy từ điểm cuối này. Bản thân điểm cuối luôn là danh sách hiện tại.

Tạo một tự động hóa #

POST /automations tạo một tự động hóa từ tên và biểu đồ. Nó được lưu ở trạng thái tắt, dưới dạng bản nháp.

Nội dung

Biểu đồ. graph_rules từ danh mục bước là ngữ pháp đầy đủ. Tóm lại:

• Mỗi nút có một id (duy nhất trong biểu đồ, ví dụ trigger_1 hoặc send_reminder), một type (một trong 8 loại bước), một label tùy chọn, và các cài đặt của nó trong data, dưới một khóa được đặt tên theo loại của nó: 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 }.
• Một tự động hóa cần ít nhất một trình kích hoạt. Ngữ pháp trực tiếp cho phép tối đa 10, và tự động hóa bắt đầu khi bất kỳ trình kích hoạt nào trong số đó được kích hoạt.
• Mọi bước khác phải có thể truy cập được từ một trình kích hoạt, và không có kết nối nào được dẫn ngược lại bước trước đó.
• Mỗi cạnh có một source và một target. Các cạnh rời khỏi một điều kiện mang theo sourceHandle true hoặc false. Các cạnh rời khỏi một vòng lặp mang theo body hoặc done. Các cạnh rời khỏi độ trễ Chờ phản hồi mang theo replied hoặc timed_out. Các cạnh khác không có sourceHandle; ngữ pháp liệt kê các phần còn lại.
• Slug và tham số hành động đến từ danh mục. Không bao giờ đoán một id (một tác nhân, một thẻ, một danh sách, một giai đoạn): hãy tra cứu nó với API trước, hoặc để trường đó là "" để người dùng chọn trong trình xây dựng.
• Vị trí là tùy chọn. Các bước không có vị trí sẽ được bố trí tự động.
• Các giá trị từ các bước trước đó được viết dưới dạng ${trigger.<field>} và ${nodes.<step>.<field>}. Xem Sử dụng những gì bước trước đó đã trả về và Biểu thức trong hướng dẫn Tự động hóa.

Biểu đồ được chấp nhận theo hai cách viết: cách của riêng trình xây dựng (các nút có type và data, các cạnh có source và target, như bên dưới) và cách mà Lấy một tự động hóa phản hồi (các nút có kind, config, action, params; các cạnh có from, to, branch). Vì vậy, bạn có thể đọc một tự động hóa, thay đổi một bước và gửi lại.

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()

Phản hồi (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 là tự động hóa đã lưu, có cùng hình dạng với Lấy một tự động hóa.
• draft là true trong khi nó đang bị tắt. Một tự động hóa mới luôn là bản nháp cho đến khi bạn kích hoạt nó, vì vậy enabled: false ở đây là bình thường, không phải lỗi.
• open_path là nơi nó mở ra trong trình xây dựng của ứng dụng.
• warnings liệt kê những thứ mà trình xây dựng không thể hoàn thành, dưới dạng các nhãn ngắn (ví dụ agent_function:not_linked). Nó trống khi mọi thứ đều sạch.

Thao tác tạo không an toàn để lặp lại một cách mù quáng. Nếu yêu cầu bị hết thời gian chờ, hãy liệt kê các tự động hóa của bạn trước khi gửi lại, nếu không bạn có thể tạo ra hai bản nháp.

Cập nhật tự động hóa #

PUT /automations/{automationId} thay đổi tên, mô tả và/hoặc biểu đồ. Chỉ gửi các trường bạn muốn thay đổi.

Phần thân: name, description, graph (tất cả đều tùy chọn, cần ít nhất một trường).

Một graph sẽ thay thế toàn bộ biểu đồ, vì vậy hãy luôn làm việc dựa trên những gì đã được lưu trữ:

1. Đọc tự động hóa bằng GET /automations/{automationId}.
2. Thay đổi những gì bạn cần trong biểu đồ đó.
3. Gửi lại toàn bộ biểu đồ, bao gồm tất cả các bước.

Khi bạn gửi lại:

• Giữ nguyên alias của mỗi bước như bạn đã nhận. Các bước sau sẽ tham chiếu đến một bước bằng bí danh của nó (${nodes.<alias>.<field>}). Nếu bạn thay đổi hoặc xóa nó, mọi tham chiếu đến bước đó sẽ trở nên trống rỗng. Xem Đặt tên cho các bước của bạn.
• Để nguyên các giá trị "[redacted]". Một giá trị được hiển thị là "[redacted]" sẽ giữ nguyên giá trị đã lưu của nó.
• Khôi phục các văn bản bị rút gọn. Văn bản kết thúc bằng dấu ba chấm là do đã bị cắt bớt khi đọc.

Trạng thái bật/tắt của tự động hóa không bao giờ bị thay đổi tại đây. Nếu nó đang bật, chỉnh sửa của bạn sẽ có hiệu lực ngay khi được lưu. Khi một tự động hóa đang bật, mọi thay đổi có thể khiến nó tự kích hoạt sẽ bị từ chối: hãy tắt nó trước.

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

Phản hồi (200): có cùng cấu trúc với một lệnh tạo (automation, draft, open_path, warnings). Nếu không gửi name, description hoặc graph, hệ thống sẽ trả về 400.

Bật và tắt #

POST /automations/{automationId}/enable sẽ bật một tự động hóa để nó chạy theo trình kích hoạt kể từ bây giờ. Chỉ gọi lệnh này sau khi chủ sở hữu tài khoản đã xem tự động hóa đó làm gì, tác động đến ai và đã đồng ý bật nó. Trình xây dựng sẽ từ chối bật một biểu đồ mà nó không thể chạy (không có trình kích hoạt, có vòng lặp, hoặc một bước tự kích hoạt chính nó) kèm theo một 400 giải thích lý do.

POST /automations/{automationId}/disable sẽ tắt nó (tạm dừng). Các lần chạy đang diễn ra sẽ hoàn tất; không có lần chạy mới nào được bắt đầu. Việc tắt luôn được cho phép.

Cả hai lệnh gọi đều không yêu cầu phần thân (body).

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"},
)

Phản hồi (200): tự động hóa như hiện tại, có cùng cấu trúc với lệnh tạo, với draft: false sau khi bật.

Lịch sử chạy #

GET /automations/{automationId}/runs trả về các lần chạy của một tự động hóa, theo thứ tự mới nhất trước: thời điểm mỗi lần chạy bắt đầu và kết thúc, nguyên nhân kích hoạt, liệu nó có thành công hay không và lỗi khi nó thất bại. Đọc tự động hóa cho bạn biết nó sẽ làm gì. Lịch sử chạy cho bạn biết nó đã làm gì, và đây là cách duy nhất để phân biệt một tự động hóa chưa bao giờ chạy với một tự động hóa chạy và thất bại mỗi lần.

Tham số truy vấn (tất cả đều tùy chọn): limit (1 đến 50, mặc định là 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"]

Phản hồi (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 là live cho một lần chạy thực tế, hoặc safe cho một Lần chạy an toàn từ trình chỉnh sửa. Lần chạy an toàn không gửi bất cứ thứ gì, vì vậy nó không phải là bằng chứng cho thấy tự động hóa hoạt động trong thực tế.
• Danh sách runs trống là một câu trả lời, không phải là thiếu sót. Phản hồi sau đó sẽ mang theo note: hoặc là trình kích hoạt chưa bao giờ được kích hoạt, hoặc tự động hóa đã bị tắt, vì vậy không có gì được chạy.

Thư mục #

Các thư mục chỉ nhóm các tự động hóa trong danh sách. Chúng không bao giờ thay đổi những gì một tự động hóa thực hiện hoặc liệu nó có đang bật hay không. Xem Sắp xếp tự động hóa vào thư mục.

Liệt kê thư mục #

GET /automations/folders trả về các thư mục, mỗi thư mục kèm theo số lượng tự động hóa mà nó chứa, cộng với unfiled_count: số lượng tự động hóa không nằm trong thư mục nào.

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
}

Tạo thư mục #

POST /automations/folders với { "name": "Appointment reminders" }. Tên là bắt buộc, tối đa 100 ký tự và phải là duy nhất trong tài khoản. Lưu trữ các tự động hóa vào đó bằng Di chuyển tự động hóa, hoặc truyền folder_id khi bạn tạo một tự động hóa.

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

Phản hồi (201): { "success": true, "folder": { "id": "...", "name": "Appointment reminders", "automation_count": 0 } }. Một tên đã tồn tại ở thư mục khác sẽ trả về 409 với code: "folder_name_taken".

Đổi tên thư mục #

PUT /automations/folders/{folderId} với { "name": "..." }. Các tự động hóa bên trong nó vẫn giữ nguyên vị trí.

Phản hồi (200): { "success": true, "folder": { ... } }.

Xóa thư mục #

DELETE /automations/folders/{folderId} chỉ xóa thư mục. Các tự động hóa bên trong không bị xóa: chúng sẽ chuyển sang trạng thái không nằm trong thư mục nào và tiếp tục chạy chính xác như trước.

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." }

Di chuyển tự động hóa vào thư mục #

PUT /automations/{automationId}/folder với { "folder_id": "<folder id>" }, hoặc { "folder_id": null } để đưa nó ra khỏi thư mục. folder_id là bắt buộc. Chỉ có vị trí liệt kê tự động hóa là thay đổi.

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" }'

Phản hồi (200): { "success": true, "automation_id": "...", "folder_id": "..." }.

Danh mục #

Các loại bước #

Trình kích hoạt #

Đây là 40 trình kích hoạt mà danh mục liệt kê hiện nay, được nhóm theo cách nhóm của trình xây dựng. Cột Cài đặt chứa các khóa cài đặt riêng của trình kích hoạt (fields), giúp thu hẹp phạm vi kích hoạt. Mỗi trình kích hoạt cũng nhận respect_quiet_hours, run_hours, reentry và stop_on_response; xem Cài đặt tự động hóa.

Nhắn tin

Liên hệ

Giao dịch

Cuộc hẹn

Nhiệm vụ

Tài khoản

Đại lý

Chung và ứng dụng

Một tự động hóa có thể chứa tối đa một trình kích hoạt cho mỗi loại webhook, app_event, agent_function, rss, schedule, email_received, appointment_upcoming và contact_added. Trình kích hoạt kích hoạt khi một bản ghi được tạo không thể ghép nối với hành động tạo ra chính bản ghi đó, vì tự động hóa sẽ tự kích hoạt chính nó.

Để biết mỗi trình kích hoạt cung cấp những gì cho các bước sau (output_keys) và danh sách đầy đủ các hành động cùng tham số của chúng, hãy đọc GET /automations/steps. Hướng dẫn Tự động hóa giải thích từng trình kích hoạt theo cách diễn đạt của trình xây dựng.

Lỗi #

Mỗi lỗi đều có dạng thông thường { "success": false, "error_code": <status>, "error": "..." }. Một biểu đồ bị từ chối sẽ thêm code và 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 liệt kê mọi vấn đề, mỗi vấn đề là một câu có thể sửa được, và error là vấn đề đầu tiên. Hãy sửa chính xác những gì được liệt kê và gửi lại toàn bộ biểu đồ. code là một trong các mã invalid_graph, automation_graph_has_a_cycle, self_triggering_automation, no_trigger, hoặc một mã khác từ trình xây dựng.

Các bước tiếp theo #

• Tự động hóa: cách các trình kích hoạt, bước, biến và lịch sử chạy hoạt động trong trình xây dựng.
• API cho Đại lý: xây dựng tự động hóa trên tài khoản khách hàng với sub_account_id.
• Tham chiếu API: trình khám phá điểm cuối tương tác đầy đủ.