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

# Large SMS and call tasks

> Upload up to 100,000 recipients and track background execution as one task.

Use `/bulk-tasks` when your recipient list exceeds the existing 1,000-recipient batch limit. One task accepts up to 100,000 recipients. It stores numbered upload chunks and prepares smaller child batches in the background after you explicitly start it. The existing `/batches` and `/sms-batches` endpoints keep their limits.

## Create an upload-only task

`POST /bulk-tasks` requires `Idempotency-Key`. Choose `kind: sms` or `kind: calls`. SMS uses `recipient_format: recipients`; calls accept either `recipients` or `contact_ids`. `options` uses the corresponding existing batch settings, including schedules, per-recipient variables, references, callbacks and `test_mode`.

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

Creating and uploading do not send messages or dial. Call tasks use `options.agent_id`. Every mutation requires `batches:write` for calls or `sms:send` for SMS. Reads require the corresponding `batches:read` or `sms:read`; having a scope for the other kind grants no access.

## Upload the complete recipient list

Send `PUT /bulk-tasks/{task_id}/chunks/{chunk_index}` with `{"recipients": [...]}`. Indexes start at 0. Every chunk must contain exactly `upload_chunk_size` recipients, except the last chunk. For a call task using `contact_ids`, the array contains UUID strings. Otherwise it contains the existing inline call or SMS recipient objects.

Upload sequentially. An unchanged index and body is safe to retry with the same key, including after a timeout. Different content at an existing index returns `409 idempotency_conflict`. Duplicate phones, contact IDs and inline call external identities anywhere in a task reject the entire new chunk. The creating API key must perform uploads and start.

```javascript theme={null}
// task is the create response; recipients is your complete local list.
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}`);
}
```

Each JSON request must fit the existing 1 MiB limit. Select a smaller `upload_chunk_size` (1–1,000) when recipient variables are large. If interrupted, resume using the same task, indexes, bodies and idempotency keys. Handle `429` using the [rate-limit response headers](https://docs.brightalk.ai/en/rate-limits.md).

## Start background execution

Send `POST /bulk-tasks/{task_id}/start` with `{}` and an `Idempotency-Key`. An incomplete upload returns `400 validation_error` with `upload_incomplete`. Starting again is safe and never duplicates the task's child batches.

> [!WARNING]
>
> Starting a task authorizes real SMS sending or AI phone calls to its recipients, at its configured time. Use `test_mode: true` while integrating; it creates test results without carrier sends, dial commands or charges.

The scheduled worker prepares up to 10 SMS recipients or 100 call recipients per part, checking current key authority and destination rules. Revoked or expired keys prevent future parts from being submitted. The existing carrier, billing, call concurrency, calling-window and retry rules still apply. Large tasks may take multiple worker cycles; a requested schedule does not promise simultaneous delivery.

Only one bulk call child per organization is active at a time, across all of its tasks, so a large task cannot fill the shared dialer shortlist. SMS preparation waits until its start time and pauses when the due delivery backlog reaches 500 recipients; this prevents mass preparation from outrunning the existing delivery worker and expiring unsent messages. Preparation runs on its own authenticated minute schedule with a 24-second cancellation deadline.

## Track progress and investigate failures

`GET /bulk-tasks/{task_id}` reports `uploaded_recipients`, `submitted_recipients`, `settled_recipients`, `failed_recipients`, `unknown_recipients` and part counts. `completed` means every recipient has a settled result, including failures. It does not mean every SMS was delivered or every call was answered. Unknown SMS delivery remains unsettled; do not resend it in a new task.

`GET /bulk-tasks/{task_id}/parts` returns at most 100 parts. Follow `next_after` using `?after=...`. Each submitted part includes `batch_id`, which uses the existing SMS or call batch query endpoints. Failed preparation parts include a fixed `error_code`; `failed_recipients` counts execution failures, while `failed_parts` identifies preparation failures that never submitted recipients.

Preparation failures make the task `failed`; previously submitted and other pending parts may continue. Task-wide cancellation and automatic replay of permanently failed parts are not provided. Use existing call batch pause/cancel endpoints for submitted call parts. Canonical contacts that resolve to the same person across call parts are rejected before that part starts. Never recreate the entire task to retry a partial or uncertain result.

The MCP equivalents are `brightalk_create_bulk_task`, `brightalk_upload_bulk_task_chunk`, `brightalk_start_bulk_task`, `brightalk_get_bulk_task` and `brightalk_list_bulk_task_parts`.


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