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

# 大型簡訊與撥號任務

> 上傳最多 100,000 筆名單，統一追蹤背景執行進度。

名單超過既有批次的 1,000 筆上限時，可使用 `/bulk-tasks`。單一任務最多 100,000 筆，先分段上傳，明確啟動後再由背景建立較小的子批次。既有 `/batches` 與 `/sms-batches` 的上限維持不變。

## 建立待上傳任務

`POST /bulk-tasks` 必須帶 `Idempotency-Key`。`kind` 選 `sms` 或 `calls`；簡訊的 `recipient_format` 使用 `recipients`，撥號可選 `recipients` 或 `contact_ids`。`options` 沿用對應批次的設定，支援排程、每筆變數、參考編號、回呼與 `test_mode`。

```json theme={null}
{
  "kind": "sms",
  "total_recipients": 10000,
  "recipient_format": "recipients",
  "upload_chunk_size": 1000,
  "options": { "message": "Hello {{name}}", "test_mode": true }
}
```

建立與上傳不會發簡訊或撥號。撥號任務需要 `options.agent_id`。寫入操作依類型需要 `batches:write` 或 `sms:send`；查詢需要對應的 `batches:read` 或 `sms:read`。只有另一種類型的權限，不能存取此任務。

## 上傳完整名單

呼叫 `PUT /bulk-tasks/{task_id}/chunks/{chunk_index}`，內容為 `{"recipients": [...]}`。編號從 0 開始，除最後一段外，每段必須剛好有 `upload_chunk_size` 筆。撥號若採 `contact_ids`，陣列放 UUID 字串；其餘格式放既有的撥號收話人或簡訊收件人物件。

請依序上傳。逾時後可沿用相同編號、內容與金鑰重試。已存在的編號若收到不同內容，會回傳 `409 idempotency_conflict`。整個任務內若有重複電話、聯絡人 ID 或撥號外部識別，新上傳的整段會被拒絕。上傳與啟動必須使用建立任務的 API 金鑰。

```javascript theme={null}
// task 為建立任務的回應；recipients 為本機的完整名單。
for (let offset = 0; offset < recipients.length; offset += task.upload_chunk_size) {
  const index = offset / task.upload_chunk_size;
  // uploadChunk wraps PUT /bulk-tasks/{task_id}/chunks/{chunk_index}.
  const response = await uploadChunk(task.id, index, {
    recipients: recipients.slice(offset, offset + task.upload_chunk_size),
  }, { idempotencyKey: `${task.id}-chunk-${index}` });
  if (!response.ok) throw new Error(`Upload paused at chunk ${index}: ${response.status}`);
}
```

每次 JSON 請求仍須小於 1 MiB。每筆變數較大時，可將 `upload_chunk_size` 設小，範圍為 1–1,000。中斷後沿用同一任務、分段編號、內容與冪等金鑰繼續。收到 `429` 時依[速率限制回應標頭](https://docs.brightalk.ai/zh-Hant/rate-limits.md)等待。

## 啟動背景執行

呼叫 `POST /bulk-tasks/{task_id}/start`，內容為 `{}`，並帶 `Idempotency-Key`。名單未上傳完整會回傳 `400 validation_error`，附帶 `upload_incomplete`。重複啟動不會重複建立子批次。

> [!WARNING]
>
> 啟動任務會授權依設定時間，對名單發送真實簡訊或進行 AI 撥號。串接測試請使用 `test_mode: true`，只建立測試結果，不會向電信商送出、建立撥號指令或扣款。

排程 worker 每個處理分段最多準備 10 筆簡訊或 100 筆撥號，並檢查當下金鑰權限與目的地規則。撤銷或過期的金鑰不能繼續提交新分段。電信發送、扣款、通話並行容量、撥號時段與重試仍沿用既有規則。大型任務可能需要多輪處理，指定排程不代表所有收件人會同時收到。

同一組織的所有大型撥號任務，合計最多同時啟動一個子批次，避免占滿共用撥號候選佇列。簡訊會等到指定時間才開始準備，待發佇列達 500 筆時暫停加入新分段，避免大量加入後來不及發送就過期。準備工作使用獨立的驗證排程，每分鐘執行，並在 24 秒時取消未完成的處理。

## 查詢進度與排查失敗

`GET /bulk-tasks/{task_id}` 提供 `uploaded_recipients`、`submitted_recipients`、`settled_recipients`、`failed_recipients`、`unknown_recipients` 及分段數量。`completed` 表示所有收件人已有確定結果，包含失敗，不代表所有簡訊都送達或所有電話都接通。簡訊送達結果不明時仍屬未結案，請勿另建任務重送。

`GET /bulk-tasks/{task_id}/parts` 每頁最多 100 個處理分段，使用 `?after=...` 接續 `next_after`。已提交分段的 `batch_id` 可搭配既有簡訊或撥號批次查詢。準備失敗會有固定 `error_code`；`failed_recipients` 計算執行失敗筆數，未提交的準備失敗則以 `failed_parts` 表示。

準備分段失敗會讓任務呈現 `failed`，但先前已提交與其餘等待中的分段仍可能繼續。目前不提供整個任務的取消操作，也不會自動重跑永久失敗分段；已提交的撥號子批次可使用既有暫停或取消操作。跨撥號分段若解析到同一位聯絡人，會在該分段啟動前拒絕。部分完成或結果不明時，請勿重建整個任務重送。

對應 MCP 工具為 `brightalk_create_bulk_task`、`brightalk_upload_bulk_task_chunk`、`brightalk_start_bulk_task`、`brightalk_get_bulk_task` 與 `brightalk_list_bulk_task_parts`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.