建立自動化執行

此流程會選取由儀表板管理且已啟用的自動化，為一位聯絡人建立一次執行，並追蹤非同步自動化執行的 API 資源。

事前準備

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

選取已啟用的自動化

以 automations:read 列出摘要，再選擇 status 為 active 的項目。請將 JavaScript 範例儲存為 .mjs，或在 ESM 專案中執行。範例最外層的 await 必須使用 ESM，且需使用 Node 18 以上版本提供的內建 fetch。

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

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

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

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

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

啟動自動化執行

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

啟動這次自動化執行可能會依儀表板管理的自動化定義撥打真實 PSTN 電話。送出此寫入操作前，請確認自動化、聯絡人、設定行為與時間。

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

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

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

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

預期回應

API 會傳回 202 Accepted。請保存自動化執行 API 資源的 id。

{
  "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`	自動化與聯絡人屬於此組織且對此組織可見
`resource_state_conflict`	所選自動化為 `active`，且請求的狀態轉換符合目前執行狀態
`validation_error`	`input_fields` 為空時，省略 `input` 或只傳送 `{}`
`duplicate_active_run`	使用安全 `details` 中的 `existing_run_id` 查詢既有且仍在進行的自動化執行
`idempotency_conflict`	重複使用的金鑰具有相同自動化、聯絡人及語意相同的請求內容

開始使用

API 基礎

核心概念

操作指南

發布資訊

API 參考

事前準備

選取已啟用的自動化

啟動自動化執行

預期回應

查詢及取消

常見錯誤

​事前準備

​選取已啟用的自動化

​啟動自動化執行

​預期回應

​查詢及取消

​常見錯誤

事前準備

選取已啟用的自動化

啟動自動化執行

預期回應

查詢及取消

常見錯誤