名單超過既有批次的 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。
建立與上傳不會發簡訊或撥號。撥號任務需要 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 金鑰。
每次 JSON 請求仍須小於 1 MiB。每筆變數較大時,可將 upload_chunk_size 設小,範圍為 1–1,000。中斷後沿用同一任務、分段編號、內容與冪等金鑰繼續。收到 429 時依速率限制回應標頭等待。
啟動背景執行
呼叫 POST /bulk-tasks/{task_id}/start,內容為 {},並帶 Idempotency-Key。名單未上傳完整會回傳 400 validation_error,附帶 upload_incomplete。重複啟動不會重複建立子批次。
啟動任務會授權依設定時間,對名單發送真實簡訊或進行 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。