建立並啟動批次

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

批次撥號分為兩個步驟：建立草稿，再明確啟動。批次可接受 1–1,000 位不重複且具權威性聯絡人紀錄的收話人。

事前準備

一把放在伺服器端，且具備精確配對 batches:write 與 batches:read 的 bt_live_ 金鑰。
符合資格的 agent_id，以及相同組織內不重複的 contact_ids 或內嵌收話人資料。
建立及啟動批次各自使用的非機密冪等性金鑰。
若要排程，請使用契約支援的 RFC 3339 start_at 和／或一段連續的每日 calling_window。

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

建立草稿

標準範例使用兩位既有聯絡人。建立後會傳回 status: draft，且不會開始撥號。

啟動此批次可能對每位收話人撥打真實 PSTN 電話。啟動前，請確認完整收話人名單、代理、排程、撥號時段與時間。

curl --request POST 'https://api.brightalk.ai/batches' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: createBatch-example-001" \
  --data '{"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}'

const response = await fetch("https://api.brightalk.ai/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "createBatch-example-001",
  },
  body: JSON.stringify({"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]}),
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "POST",
    "https://api.brightalk.ai/batches",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "createBatch-example-001",
    },
    json={"name":"Renewal reminders","agent_id":"agt_demo_001","contact_ids":["con_demo_001","con_demo_002"]},
)
print(response.status_code, response.json())

預期草稿

API 會以 201 Created 傳回彙總數量。請保存批次的 id。

{
  "id": "bat_demo_001",
  "name": "Renewal reminders",
  "agent_id": "agt_demo_001",
  "total_recipients": 2,
  "pending_recipients": 2,
  "queued_recipients": 0,
  "in_progress_recipients": 0,
  "completed_recipients": 0,
  "failed_recipients": 0,
  "cancelled_recipients": 0,
  "answered_recipients": 0,
  "no_answer_recipients": 0,
  "busy_recipients": 0,
  "created_at": "2026-07-20T01:00:00Z",
  "updated_at": "2026-07-20T01:00:00Z",
  "status": "draft"
}

繼續前，請檢查傳回的資源識別與數量。不要略過明確的啟動狀態轉換。

啟動批次

將 bat_demo_001 替換為傳回的 id。立即啟動時會傳回 status: queued；若已設定未來的符合資格時間，則可能傳回 status: scheduled。

curl --request POST 'https://api.brightalk.ai/batches/bat_demo_001/start' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: startBatch-example-001" \
  --data '{}'

const response = await fetch("https://api.brightalk.ai/batches/bat_demo_001/start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGHTALK_API_KEY}`,
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "startBatch-example-001",
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.json());

import os
import requests

response = requests.request(
    "POST",
    "https://api.brightalk.ai/batches/bat_demo_001/start",
    headers={
    "Authorization": f"Bearer {os.environ['BRIGHTALK_API_KEY']}",
    "Brightalk-Version": "2026-07-16",
    "Content-Type": "application/json",
    "Idempotency-Key": "startBatch-example-001",
    },
    json={},
)
print(response.status_code, response.json())

啟動操作會傳回 202 Accepted。容量限制可能讓符合資格的收話人留在佇列；請監控彙總數量，不要將排隊視為錯誤。

查詢及控制

請沿用同一個批次 id，並保留必要的權限配對。

動作	端點	下一個動作
查詢	`GET /batches/{batch_id}`	採退避方式查詢，直到 `completed`、`failed` 或 `cancelled`
暫停	`POST /batches/{batch_id}/pause`	停止後續派送；進行中的通話可能繼續
繼續	`POST /batches/{batch_id}/resume`	將符合資格的剩餘收話人重新加入佇列
取消	`POST /batches/{batch_id}/cancel`	停止剩餘工作，並以盡力而為方式要求取消進行中的工作

暫停、繼續與取消可選用 Idempotency-Key。動作可能重試時，請使用此標頭。

常見錯誤

錯誤	檢查項目
`validation_error`	共有 1–1,000 位不重複的收話人、只使用一種收話人格式，且排程／撥號時段有效
`insufficient_scope`	金鑰具備控制所需的 `batches:write`，以及查詢所需的 `batches:read`
`resource_state_conflict`	只啟動 `draft`、只暫停有效工作，且請求的狀態轉換符合目前狀態
`unsupported_destination`	派送前已確認每個目的地都已啟用
`idempotency_conflict`	建立與啟動分別使用自己的穩定金鑰，且語意相同的請求內容未改變
`rate_limit_exceeded`	等待數字 `Retry-After`；重試相同動作時保留相同金鑰

開始使用

API 基礎

核心概念

操作指南

發布資訊

API 參考

事前準備

建立草稿

預期草稿

啟動批次

查詢及控制

常見錯誤

​事前準備

​建立草稿

​預期草稿

​啟動批次

​查詢及控制

​常見錯誤

事前準備

建立草稿

預期草稿

啟動批次

查詢及控制

常見錯誤