Create and start a batch

Batch dialing is a two-step flow: create a draft, then explicitly start it. A batch accepts 1–1,000 unique canonical recipients.

Prerequisites

A server-side bt_live_ key with batches:write and batches:read.
An eligible agent_id and either unique contact_ids or unique inline recipients from the same organization.
Separate nonsecret idempotency keys for creating and starting the batch.
If scheduling, an RFC 3339 start_at and/or one contiguous daily calling_window supported by the contract.

Save JavaScript samples as .mjs or run them in an ESM project. Their top-level await requires ESM, and Node 18 or later provides the built-in fetch they use.

Create the draft

The canonical example uses two existing contacts. Creation returns status: draft and does not begin dialing.

Starting this batch can place real PSTN calls to every recipient. Verify the complete recipient set, agent, schedule, calling window, and timing before starting it.

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())

Expected draft

The API returns 201 Created with aggregate counts. Save the batch 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"
}

Review the returned identity and counts before continuing. Do not skip the explicit start transition.

Start the batch

Replace bat_demo_001 with the returned id. Starting immediately returns status: queued; configured scheduled eligibility can return 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())

The start operation returns 202 Accepted. Capacity can keep eligible recipients queued; monitor aggregate counts instead of treating queueing as an error.

Inspect and control

Use the same batch id and preserve the required scope pair.

Action	Endpoint	Next action
Inspect	`GET /batches/{batch_id}`	Poll with backoff until `completed`, `failed`, or `cancelled`
Pause	`POST /batches/{batch_id}/pause`	Stops subsequent dispatch; active calls may continue
Resume	`POST /batches/{batch_id}/resume`	Requeues eligible remaining recipients
Cancel	`POST /batches/{batch_id}/cancel`	Stops remaining work and requests best-effort active cancellation

Pause, resume, and cancel accept an optional Idempotency-Key. Use one when an action might be retried.

Common errors

Error	What to check
`validation_error`	There are 1–1,000 unique canonical recipients, exactly one recipient form, and a valid schedule/window
`insufficient_scope`	The key has `batches:write` for controls and `batches:read` for inspection
`resource_state_conflict`	Only a `draft` is started; only `scheduled`, `queued`, or `in_progress` work is paused; and the requested transition fits the current state
`unsupported_destination`	Every destination is enabled before dispatch
`idempotency_conflict`	Create and start each have their own stable key and unchanged semantic body
`rate_limit_exceeded`	Wait for numeric `Retry-After`; keep the same key when retrying the same action

Get started

API fundamentals

Core concepts

Guides

Release information

API reference

Prerequisites

Create the draft

Expected draft

Start the batch

Inspect and control

Common errors

​Prerequisites

​Create the draft

​Expected draft

​Start the batch

​Inspect and control

​Common errors

Prerequisites

Create the draft

Expected draft

Start the batch

Inspect and control

Common errors