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

# 建立並啟動批次

> 建立批次草稿、啟動撥號並追蹤批次狀態。

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

批次撥號分為兩個步驟：建立草稿，再明確啟動。批次可接受 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`，且不會開始撥號。

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

<CodeGroup>
  ```curl theme={null}
  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"]}'
  ```

  ```javascript theme={null}
  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());
  ```

  ```python theme={null}
  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())
  ```
</CodeGroup>

## 預期草稿

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

```json theme={null}
{
  "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`。

<CodeGroup>
  ```curl theme={null}
  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 '{}'
  ```

  ```javascript theme={null}
  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());
  ```

  ```python theme={null}
  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())
  ```
</CodeGroup>

啟動操作會傳回 `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`；重試相同動作時保留相同金鑰                 |