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

# Automations

> 理解由儀表板管理的 Automation 與其 API 執行方式。

<Note>
  **私人測試版。** 新組織預設已啟用。組織管理員仍須在 Brightalk 設定中建立具權限範圍的 API 金鑰，請求才能通過驗證。可用範圍與限制以本文件和 OpenAPI 契約為準。
</Note>

Automation 是由儀表板管理的定義，負責自己的代理、等待條件、撥號行為、重試規則、分支流程與後續動作。REST API 只會列出摘要及啟動執行，不會在請求中重新定義這些行為。

## 選取有效 Automation

`GET /automations?status=active` 會傳回組織可見的摘要，包含 `id`、`name`、`description`、`status` 與 `input_fields`。請將傳回的 `id` 作為 `automation_id`。本 API 只提供唯讀目錄。

## 理解 `input_fields` 宣告

目前版本的宣告為空：

```json theme={null}
{
  "id": "atm_demo_001",
  "name": "Renewal follow-up",
  "description": "Calls one contact and records the outcome.",
  "status": "active",
  "input_fields": []
}
```

`input_fields` 為空時，請在 `POST /automation-runs` 省略 `input`，或只傳送 `{}`。不要傳送未宣告的名稱。

## 啟動執行

`POST /automation-runs` 接受一個有效的 `automation_id`，以及一個既有聯絡人或內嵌收話人資料。它不接受代理覆寫、時間覆寫、重試規則或分支選擇。回應是一個非同步的 Automation 執行 API 資源。

只有後續 API 回應傳回非空的 `input_fields` 宣告時，客戶端才能傳送其中明確列出的欄位。請以 API 傳回的宣告為準。

## 追蹤及取消

請查詢 Automation 執行，直到 `status` 進入終止狀態。相同 Automation 與聯絡人已有另一個有效執行時，可能傳回 `409 duplicate_active_run`，並在安全的 `details` 中提供既有執行 ID。

取消會阻止排隊中的工作啟動，或在執行步驟的邊界之間，將非終止狀態的 Automation 執行標記為 `cancelled`。取消不會中斷正在執行的步驟，外部效果仍採盡力而為。所有 API 狀態請參閱[狀態生命週期](/zh-Hant/concepts/status-lifecycle)。