> ## 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.

# 執行 Automation

> 為單一聯絡人啟動並追蹤 Automation 執行。

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

此流程會選取由儀表板管理的有效 Automation、為一位聯絡人啟動，並追蹤非同步 Automation 執行的 API 資源。

## 事前準備

* 一把放在伺服器端，且具備精確配對 `automations:run` 與 `automations:read` 的 `bt_live_` 金鑰。
* 一個組織可見的有效 Automation，以及一個既有聯絡人或內嵌收話人資料。
* 此次邏輯執行專用且不重複、非機密的 `Idempotency-Key`。
* 瞭解代理、等待條件、重試規則與分支流程都由 Automation 負責，而不是由 API 請求決定。

## 選取有效 Automation

以 `automations:read` 列出摘要，再選擇 `status` 為 `active` 的項目。

請將 JavaScript 範例儲存為 `.mjs`，或在 ESM 專案中執行。範例最外層的 `await` 必須使用 ESM，且需使用 Node 18 以上版本提供的內建 `fetch`。

<CodeGroup>
  ```curl theme={null}
  curl --request GET 'https://api.brightalk.ai/automations?status=active&limit=20' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16"
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/automations?status=active&limit=20", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
    },
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "GET",
      "https://api.brightalk.ai/automations?status=active&limit=20",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      },
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

目前版本的摘要沒有宣告可由 API 傳入的欄位：

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

## 啟動 Automation 執行

因 `input_fields` 為空，請如標準範例一樣省略 `input`，或只傳送 `{}`。

<Warning>
  啟動 Automation 可能依儀表板管理的定義撥打真實 PSTN 電話。送出此寫入操作前，請確認 Automation、聯絡人、設定行為與時間。
</Warning>

<CodeGroup>
  ```curl theme={null}
  curl --request POST 'https://api.brightalk.ai/automation-runs' \
    --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
    --header "Brightalk-Version: 2026-07-16" \
    --header "Content-Type: application/json" \
    --header "Idempotency-Key: createAutomationRun-example-001" \
    --data '{"automation_id":"atm_demo_001","contact_id":"con_demo_001"}'
  ```

  ```javascript theme={null}
  const response = await fetch("https://api.brightalk.ai/automation-runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createAutomationRun-example-001",
    },
    body: JSON.stringify({"automation_id":"atm_demo_001","contact_id":"con_demo_001"}),
  });
  console.log(response.status, await response.json());
  ```

  ```python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.brightalk.ai/automation-runs",
      headers={
      "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
      "Brightalk-Version": "2026-07-16",
      "Content-Type": "application/json",
      "Idempotency-Key": "createAutomationRun-example-001",
      },
      json={"automation_id":"atm_demo_001","contact_id":"con_demo_001"},
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

只有 API 傳回非空的 `input_fields` 宣告時才能提供 `input`，而且只能傳送其中明確列出的欄位。

## 預期回應

API 會傳回 `202 Accepted`。請保存 Automation 執行 API 資源的 `id`。

```json theme={null}
{
  "id": "run_demo_001",
  "automation_id": "atm_demo_001",
  "contact_id": "con_demo_001",
  "input": {},
  "queued_at": "2026-07-20T01:00:00Z",
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "status": "queued"
}
```

## 查詢及取消

| 動作 | 端點                                      | 下一個動作                                                                             |
| -- | --------------------------------------- | --------------------------------------------------------------------------------- |
| 查詢 | `GET /automation-runs/{run_id}`         | 在 `queued`、`running` 或 `waiting` 時採退避方式查詢；於 `completed`、`failed` 或 `cancelled` 停止 |
| 取消 | `POST /automation-runs/{run_id}/cancel` | 阻止排隊中的工作，或要求在執行步驟的邊界之間取消                                                          |

查詢需要 `automations:read`；取消需要 `automations:run`。取消可選用 `Idempotency-Key`，且對正在執行的步驟仍採盡力而為。

## 常見錯誤

| 錯誤                        | 檢查項目                                                         |
| ------------------------- | ------------------------------------------------------------ |
| `insufficient_scope`      | 金鑰具備啟動／取消所需的 `automations:run`，以及列出／查詢所需的 `automations:read` |
| `resource_not_found`      | Automation 與聯絡人屬於此組織且對此組織可見                                  |
| `resource_state_conflict` | 所選 Automation 為 `active`，且請求的狀態轉換符合目前執行狀態                    |
| `validation_error`        | `input_fields` 為空時，省略 `input` 或只傳送 `{}`                      |
| `duplicate_active_run`    | 使用安全 `details` 中的 `existing_run_id` 查詢既有的有效執行                |
| `idempotency_conflict`    | 重複使用的金鑰具有相同 Automation、聯絡人及語意相同的請求內容                         |