# 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](../automations/automations.md). 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](authentication.md))
- **Các trường và nội dung**: mọi tham số và trường phản hồi đều nằm trong [Tài liệu tham khảo API](reference.md#tag/automations)
- **Lỗi**: xem [Lỗi & Phân trang](errors-and-pagination.md) và [Lỗi](#errors) bên dướ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ý](../agency/api-for-agencies.md).

---

## 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](../settings/team-management.md): 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.

---

## Các điểm cuối (Endpoints)

| Tác vụ | Phương thức + đường dẫn | Trình khám phá |
|---|---|---|
| Liệt kê các tự động hóa | `GET /automations` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/GET/automations) |
| Lấy một tự động hóa cùng với biểu đồ của nó | `GET /automations/{automationId}` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/GET/automations/{automationId}) |
| Đọc danh mục bước | `GET /automations/steps` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/GET/automations/steps) |
| Tạo một tự động hóa (bản nháp) | `POST /automations` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/POST/automations) |
| Cập nhật một tự động hóa | `PUT /automations/{automationId}` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/PUT/automations/{automationId}) |
| Bật tự động hóa | `POST /automations/{automationId}/enable` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Tắt tự động hóa | `POST /automations/{automationId}/disable` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Đọc lịch sử chạy | `GET /automations/{automationId}/runs` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Liệt kê các thư mục | `GET /automations/folders` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/GET/automations/folders) |
| Tạo một thư mục | `POST /automations/folders` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/POST/automations/folders) |
| Đổi tên một thư mục | `PUT /automations/folders/{folderId}` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Xóa một thư mục | `DELETE /automations/folders/{folderId}` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Di chuyển tự động hóa vào thư mục | `PUT /automations/{automationId}/folder` | [Mở trong Tài liệu tham khảo API](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Đọc các tự động hóa

`GET /automations` trả về các bản tóm tắt (không bao gồm các bước), sắp xếp theo thứ tự thay đổi gần nhất trước; `folder_id=none` liệt kê các tự động hóa không nằm trong thư mục nào. `GET /automations/{automationId}` thêm `graph` đầy đủ: mỗi bước (`nodes[]`) với `kind`, `label`, `alias`, `action`, `params` và `config` của nó, cùng các kết nối (`edges[]`) với `from`, `to` và, sau một điều kiện hoặc tương tự, `branch`.

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

**Điều cần biết**

- **`alias` là cách các bước sau đọc đầu ra của một bước**, dưới dạng `${nodes.<alias>.<field>}`. Một bước không có đầu ra sẽ được tham chiếu bằng id của nó.
- `params` được giữ lại cho các trình đọc cũ; `config` mang các giá trị tương tự và nhiều hơn thế (các quy tắc của điều kiện, lời nhắc của bước AI, thời lượng của độ trễ, slug và tham số của hành động).
- **Các thông tin bảo mật bị ẩn.** Các giá trị trông giống như thông tin xác thực (bí mật webhook, token, khóa API, mật khẩu, giá trị tiêu đề) sẽ trả về dưới dạng `"[redacted]"`. Gửi lại `"[redacted]"` 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 gọ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 điền đầy đủ văn bản vào trước.
- 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`, không bao giờ là một danh sách trống. Danh sách trống luôn có nghĩa là không có tự động hóa nào.

### Danh mục bước

`GET /automations/steps` trả về mọi thứ có thể dùng để xây dựng một tự động hóa: 8 `node_kinds`, mọi trình kích hoạt với cài đặt `fields` và `output_keys` của nó, các `actions` tích hợp sẵn với tham số 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), cú pháp `graph_rules`, và `counts`. Đâ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 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.

- Nếu không có `q`, hàng trăm hành động API 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ới `q` (một từ không phân biệt chữ hoa chữ thường), `api_actions` là danh sách phẳng các kết quả khớp, giới hạn ở 60 (`api_actions_truncated` cho biết khi nào). 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 mục cho biết liệu tài khoản có ứng dụng đó `connected` hay không, và `connected_apps` liệt kê các ứng dụng đã kết nối. `app_actions_unavailable` là `true` khi các hành động của ứng dụng không thể tìm kiếm được trong lần này; các danh sách khác vẫn đầy đủ.

---

## Tạo và chỉnh sửa

### Tạo bản nháp

```bash
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" }]
    }
  }'
```

```json
{ "success": true, "automation": { "id": "8d2c7f1e-…", "enabled": false, "…": "…" }, "draft": true, "open_path": "/automations/8d2c7f1e-…", "warnings": [] }
```

`draft: true` và `enabled: false` là bình thường, không phải lỗi: 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ó. `warnings` liệt kê những gì 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`).

**Viết biểu đồ.** `graph_rules` từ danh mục là cú pháp đầy đủ. Tóm lại:

- Mỗi nút có một `id` (duy nhất trong biểu đồ), một `type` (một trong 8 [loại bước](#step-kinds)), 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`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Một tự động hóa cần ít nhất một trình kích hoạt. Cú pháp trực tiếp cho phép tối đa 10 trình kích hoạt và tự động hóa sẽ bắt đầu khi bất kỳ trình kích hoạt nào trong số đó hoạt động.
- 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 đó.
- Các cạnh rời khỏi một điều kiện mang `sourceHandle` `true` hoặc `false`; một vòng lặp `body` hoặc `done`; một độ trễ Chờ phản hồi `replied` hoặc `timed_out`. Các cạnh khác không có gì.
- Slug và tham số hành động đến từ danh mục. **Không bao giờ đoán 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ó bằng API trước, hoặc để trường đó là `""` để người dùng chọn trong trình xây dựng.
- Các vị trí là tùy chọn; các bước không có vị trí sẽ được sắp xếp 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ề](../automations/automations.md#using-what-an-earlier-step-returned) và [Biểu thức](../automations/automations.md#expressions).
- Biểu đồ được chấp nhận theo hai cách viết: cách của trình xây dựng (ở trên) và cách mà một phản hồi đọc trả về (`kind`, `config`, `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.
- **Việc tạo không an toàn để lặp lại một cách mù quáng.** Nếu một yêu cầu 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

`PUT /automations/{automationId}` thay đổi `name`, `description` và/hoặc `graph` (ít nhất một, hoặc `400`). 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ữ: đọc nó, thay đổi những gì bạn cần, và gửi lại toàn bộ biểu đồ.

```bash
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)" }'
```

- **Giữ nguyên `alias` của mỗi bước như khi bạn nhận được.** Nếu 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](../automations/automations.md#naming-your-steps).
- **Để nguyên các giá trị `"[redacted]"`**, và **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 đã 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 ở đâ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 nó đang bật, một thay đổi có thể khiến nó tự kích hoạt sẽ bị từ chối: hãy tắt nó trước.

### 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ì, đối với ai và đã đồng ý. Trình xây dựng sẽ từ chối bật một biểu đồ không thể chạy (không có trình kích hoạt, bị 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.

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

`POST /automations/{automationId}/disable` sẽ tạm dừng nó: 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 bắt đầu. Việc vô hiệu hóa luôn được cho phép. Cả hai lệnh gọi đều không cần phần thân (body).

---

## 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, lần mới nhất trước (`limit` từ 1 đến 50, mặc định là 10): thời điểm bắt đầu và kết thúc, nguyên nhân kích hoạt, trạng thái thành công và lỗi khi thất bại. Việc đọ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 nhưng luôn thất bại.

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

- `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 một `note`: hoặc là trình kích hoạt chưa bao giờ hoạt động, hoặc tự động hóa đã bị tắt.

---

## 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](../automations/automations.md#organizing-automations-in-folders).

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

- Liệt kê các thư mục cũng trả về `unfiled_count`, cho biết có bao nhiêu tự động hóa không nằm trong thư mục nào.
- Tên thư mục là bắt buộc, tối đa 100 ký tự và phải là duy nhất trong tài khoản (`409`, `code: "folder_name_taken"`). Bạn cũng có thể lưu trữ một tự động hóa bằng cách truyền `folder_id` khi tạo nó.
- Việc đổi tên không làm thay đổi vị trí của các tự động hóa.
- **Xóa một thư mục chỉ xóa thư mục đó.** Các tự động hóa bên trong sẽ chuyển ra ngoài thư mục và tiếp tục chạy chính xác như trước; phản hồi sẽ cho biết có bao nhiêu tự động hóa đã được di chuyển (`moved_to_no_folder`).
- Khi di chuyển, `folder_id` là bắt buộc; hãy gửi `null` để đưa tự động hóa ra khỏi thư mục của nó.

---

## Danh mục

### Các loại bước

| Loại | Chức năng |
|---|---|
| `trigger` | Bắt đầu tự động hóa khi có sự kiện xảy ra. |
| `action` | Chạy một bước: một hành động tích hợp sẵn, hành động API, hành động của ứng dụng được kết nối, yêu cầu HTTP hoặc email. |
| `condition` | Chia luồng dựa trên một quy tắc, thành nhánh `true` và nhánh `false`. |
| `transform` | Chạy một đoạn mã ngắn để định hình lại dữ liệu giữa các bước. |
| `ai` | Hỏi AI với một câu lệnh (prompt) do bạn viết. Nó có thể trả về văn bản, các trường riêng biệt hoặc chọn một trong nhiều nhánh. |
| `delay` | Chờ trong một khoảng thời gian nhất định, hoặc chờ liên hệ phản hồi (có thời gian chờ). |
| `loop` | Lặp lại các bước bên trong cho mỗi mục trong danh sách. |
| `respond` | Trả về phản hồi cho lệnh gọi webhook hoặc lệnh gọi hàm đại lý AI đã bắt đầu lần chạy. |

### 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](../automations/automations.md#automation-settings).

**Nhắn tin**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Tin nhắn đến (`incoming_message`) | Một liên hệ gửi tin nhắn trên bất kỳ kênh nào. | `campaign` (giới hạn cho một đại lý AI), `channel`, `message_filter_contains` (từ khóa), `message_filter_regex` (mẫu) |
| Cuộc gọi nhỡ (`missed_call`) | Ai đó gọi vào một trong các số WhatsApp Web hoặc số SMS của bạn và không ai bắt máy. | `to_number` |
| Tin nhắn đã gửi (`message_delivered`) | Tin nhắn bạn gửi được kênh xác nhận đã gửi thành công. | `channel`, `agent` |
| Tin nhắn thất bại (`message_failed`) | Tin nhắn bạn gửi không thể gửi được, kèm theo lỗi. | `channel`, `agent` |
| Tin nhắn đã gửi đi (`message_sent`) | Bất kỳ tin nhắn nào rời khỏi tài khoản của bạn: của AI, của bạn, tin nhắn quảng bá, tin nhắn theo dõi. Lọc nó, nếu không nó sẽ chạy trên tất cả. | `channel`, `sent_by` |
| Tin nhắn theo dõi đã gửi (`follow_up_sent`) | Một tin nhắn theo dõi tự động được gửi đi. | không có |
| Tin nhắn theo dõi bị bỏ qua (`follow_up_skipped`) | Một tin nhắn theo dõi bị giữ lại vì điều kiện gửi không thỏa mãn. | không có |
| Tin nhắn theo dõi đã hoàn tất (`follow_up_exhausted`) | Một liên hệ đã nhận tin nhắn theo dõi cuối cùng trong chuỗi và không còn gì trong hàng đợi. | không có |
| Cuộc hội thoại đã đóng (`conversation_closed`) | Một cuộc trò chuyện được đóng lại, kèm theo cách kết thúc và tóm tắt. | `channel`, `agent` |
| Tin nhắn quảng bá đã hoàn tất (`broadcast_completed`) | Một tin nhắn quảng bá đã gửi xong, kèm theo số lượng đã gửi và số lượng thất bại. | không có |
| Phản hồi khách hàng tiềm năng đã phân loại (`outreach_reply_labelled`) | Phản hồi của khách hàng tiềm năng qua email lạnh được phân loại, ví dụ như Quan tâm. | `label` |
| Nhận bình luận Skool (`skool_comment_received`) | Một thành viên bình luận dưới bài đăng Skool mà một trong các quy tắc bình luận của bạn đang theo dõi. | không có |

**Liên hệ**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Liên hệ mới (`contact_created`) | Một người mới liên hệ với bạn lần đầu trên bất kỳ kênh nào, và cũng áp dụng cho nhập dữ liệu, API và các liên hệ bạn tự tạo thủ công. | không có |
| Liên hệ đã cập nhật (`contact_updated`) | Một trường thông tin liên hệ thay đổi. | `field` |
| Liên hệ bạn thêm vào đây (`contact_added`) | Chỉ dành cho các liên hệ bạn tự đưa vào tự động hóa này từ trang Liên hệ. Một lần chạy cho mỗi liên hệ. | không có |
| Thẻ đã áp dụng (`tag_applied`) | Một thẻ được thêm vào liên hệ, bởi đại lý AI, người dùng, tự động hóa hoặc nhập dữ liệu. | `tag_name`, `channel`, `applied_by` |
| Thẻ đã xóa (`tag_removed`) | Một thẻ bị xóa khỏi liên hệ. | `tag_name`, `channel` |
| Thành viên Skool đã tham gia (`skool_member_joined`) | Ai đó tham gia cộng đồng Skool mà bạn sở hữu hoặc quản lý, kèm theo hồ sơ, câu trả lời và điểm phù hợp của họ. | `group_id`, `create_contact` |
| Thành viên Skool đã đạt chuẩn (`skool_member_qualified`) | Câu trả lời của thành viên Skool mới đạt hoặc vượt ngưỡng của bạn. | `min_score` |

**Giao dịch**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Giao dịch đã tạo (`deal_created`) | Một giao dịch mới được thêm vào một trong các quy trình của bạn. | `pipeline_id`, `stage_id` |
| Giai đoạn giao dịch đã thay đổi (`deal_stage_changed`) | Một giao dịch chuyển sang giai đoạn khác, nêu tên giai đoạn đã rời đi và giai đoạn đã chuyển đến. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Giao dịch đã cập nhật (`deal_updated`) | Một trường thông tin giao dịch thay đổi. | `field` |

**Cuộc hẹn**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Cuộc hẹn đã đặt (`appointment_booked`) | Một cuộc hẹn mới được đặt. | không có |
| Cuộc hẹn đã hủy (`appointment_cancelled`) | Một cuộc hẹn đã đặt bị hủy. | không có |
| Cuộc hẹn đã đổi lịch (`appointment_rescheduled`) | Một cuộc hẹn đã đặt được chuyển sang thời gian khác, kèm theo thời gian cũ và thời gian mới. | `event_id` |
| Trước cuộc hẹn (`appointment_upcoming`) | Một khoảng thời gian nhất định trước mỗi cuộc hẹn đã xác nhận, dùng để nhắc nhở. Tối đa năm lời nhắc mỗi tự động hóa. | `offsets_minutes` |

**Nhiệm vụ**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Nhiệm vụ đã tạo (`task_created`) | Một nhiệm vụ được tạo. | `task_type` |
| Nhiệm vụ đã hoàn thành (`task_completed`) | Một nhiệm vụ được chuyển sang giai đoạn hoàn thành. | không có |

**Tài khoản**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Số dư tín dụng thấp (`low_credit_balance`) | Số dư tín dụng của bạn giảm xuống dưới ngưỡng cảnh báo. | không có |
| Kênh đã kết nối (`channel_connected`) | Một trong các kênh của bạn kết nối thành công. | `channel` |
| Kênh đã ngắt kết nối (`channel_disconnected`) | Một trong các kênh của bạn bị ngắt: đăng xuất, hủy liên kết hoặc bị cắt. Số WhatsApp Web tự kết nối lại chỉ được tính nếu nó vẫn ngoại tuyến sau 30 phút. | `channel` |

**Đại lý**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Tạo tài khoản phụ (`sub_account_created`) | Một tài khoản khách hàng mới được tạo từ bảng điều khiển, API hoặc trang đăng ký của bạn. | không có |
| Hoạt động của tài khoản phụ (`sub_account_event`) | Có sự kiện xảy ra trên một trong các tài khoản khách hàng của bạn: tín dụng sắp hết, kết nối kênh, thay đổi gói. | `event`, `threshold` |

**Chung và ứng dụng**

| Trình kích hoạt (`kind`) | Kích hoạt khi | Cài đặt |
|---|---|---|
| Theo lịch trình (`schedule`) | Theo lịch cron. | `cron`, `timezone` |
| Webhook (`webhook`) | Một hệ thống bên ngoài gọi địa chỉ webhook của tự động hóa. | `webhook_secret` |
| Hàm Tác nhân AI (`agent_function`) | Tác nhân AI của bạn gọi tự động hóa này như một hàm trong cuộc trò chuyện. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Mục nguồn cấp dữ liệu mới (`rss`) | Một mục mới xuất hiện trong nguồn cấp RSS hoặc Atom. | `feed_url` |
| Email đã nhận (`email_received`) | Một email đến trong hộp thư được kết nối của bạn. | `from_contains`, `subject_contains` |
| Sự kiện ứng dụng (`app_event`) | Một sự kiện xảy ra trong ứng dụng được kết nối: giai đoạn giao dịch thay đổi, thanh toán được thực hiện, biểu mẫu được gửi. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Chạy thủ công (`manual`) | Chỉ khi được khởi chạy bằng tay. | không có |

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](../automations/automations.md#triggers) 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`: `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.

| Trạng thái | Khi nào |
|---|---|
| `400` | Biểu đồ bị từ chối, thiếu trường bắt buộc (`name` hoặc `graph` khi tạo, `folder_id` khi di chuyển), bản cập nhật không gửi thay đổi nào, id không hợp lệ, hoặc tên thư mục bị thiếu, trống hoặc quá dài (`code: "invalid_name"`). |
| `403` | Tài khoản không có Tự động hóa; gói của tài khoản khách hàng không bao gồm việc tạo và chỉnh sửa tự động hóa (chỉ ghi); hoặc quyền truy cập **Tự động hóa** của thành viên nhóm quá thấp. |
| `404` | Không có tự động hóa nào với id đó trong tài khoản này, không có thư mục nào với id đó (`code: "folder_not_found"`), hoặc một `sub_account_id` không phải là một trong các tài khoản khách hàng của bạn. |
| `409` | Một thư mục với tên đó đã tồn tại (`code: "folder_name_taken"`). |
| `413` | Tự động hóa lớn hơn 1 MB mà trình xây dựng chấp nhận. Hãy di chuyển mã hoặc dữ liệu lớn ra khỏi các bước của nó. |
| `422` | Trình xây dựng từ chối yêu cầu vì lý do khác. Kiểm tra biểu đồ so với `GET /automations/steps`; việc gửi lại cùng một yêu cầu sẽ không giúp ích gì. |
| `503` | Không thể kết nối với dịch vụ tự động hóa. Hãy thử lại sau một lát. Đối với việc tạo mới, hãy liệt kê các tự động hóa của bạn trước để tránh tạo bản nháp thứ hai. |

::: master-only
## Sử dụng các điểm cuối này qua MCP

Mọi điểm cuối trên trang này cũng là một công cụ cho trợ lý AI mà bạn [kết nối qua MCP](../integrations/connect-ai-clients.md), với các quy tắc tương tự: một tự động hóa mới là bản nháp cho đến khi nó được bật, và một chỉnh sửa đối với tự động hóa đang chạy sẽ có hiệu lực ngay lập tức.

| Công cụ | Điểm cuối |
|---|---|
| `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` |
:::

---

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

- [Tự động hóa](../automations/automations.md): 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ý](../agency/api-for-agencies.md): 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](reference.md): trình khám phá điểm cuối tương tác đầy đủ.