Batch calling

A call batch dials a list of people with one agent from one of your numbers, on a schedule, with retries and a circuit breaker. It is also how you schedule a single call for later: a one-row batch. Every call is placed exactly as a single outbound call, hosted in the from-number’s region.

Voicemail is answered and billed unless the agent has voicemail_detection on. With it on, the call ends as voicemail, the recipient is retried like a missed call, and counts.voicemail counts them. Without it, voicemail counts as reached and is never retried.
Every call runs the agent’s current published version. A republish mid-campaign changes every later call. A publish the batch could not dial with (a non-voice channel, or a new required variable its vars do not supply) is refused until the batch is cancelled or over.

Create a batch

curl -sS https://api.talqing.com/v1/calls/batches \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October renewals",
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "from_phone_number_id": "8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2",
    "timezone": "Asia/Kolkata",
    "calling_window": { "start": "10:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "max_concurrency": 3,
    "max_attempts": 2,
    "retry_after_minutes": 45,
    "recipients": [
      { "to": "+919876543210", "userdata": { "first_name": "Priya", "policy": "NW-40182" } },
      { "to": "+919812345678", "userdata": { "first_name": "Arjun", "policy": "NW-40311" } }
    ]
  }'

const batch = await talqing.calls.batches.create({
  createCallBatchRequest: {
    name: "October renewals",
    agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    from_phone_number_id: "8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2",
    timezone: "Asia/Kolkata",
    calling_window: { start: "10:00", end: "18:00", days: [1, 2, 3, 4, 5] },
    max_concurrency: 3,
    max_attempts: 2,
    retry_after_minutes: 45,
    recipients: [
      { to: "+919876543210", userdata: { first_name: "Priya", policy: "NW-40182" } },
      { to: "+919812345678", userdata: { first_name: "Arjun", policy: "NW-40311" } },
    ],
  },
});
console.log(batch.status, batch.next_dial_at);

batch = talqing.calls.batches.create(
    name="October renewals",
    agent_id="9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    from_phone_number_id="8b41d0e6-2c77-4a19-b3f5-91ad6e40c8b2",
    timezone="Asia/Kolkata",
    calling_window={"start": "10:00", "end": "18:00", "days": [1, 2, 3, 4, 5]},
    max_concurrency=3,
    max_attempts=2,
    retry_after_minutes=45,
    recipients=[
        {"to": "+919876543210", "userdata": {"first_name": "Priya", "policy": "NW-40182"}},
        {"to": "+919812345678", "userdata": {"first_name": "Arjun", "policy": "NW-40311"}},
    ],
)
print(batch["status"], batch["next_dial_at"])

Validation is all-or-nothing and reports every bad row at once: an unparseable number, a number repeated in the payload, a reserved userdata key. to is normalized against the from-number’s country, as on a single call. Each recipient’s userdata is a flat map of strings that becomes that call’s session state ({{userdata.first_name}}). An empty value is dropped, so the placeholder resolves to nothing. There are no per-recipient overrides of the agent, number or schedule; a different agent means a different batch. Batch-level vars is one bag copied onto every call; it is fixed at create.

Fields

Field	Range	Default	Meaning
`name`	1–200 chars	required
`from_phone_number_id`	uuid	required	Outbound-capable, `active` number on a `ready` account.
`recipients`	1–10,000	required	Per request; append more later. Each is `{to, userdata}`.
`timezone`	IANA zone	required	Interprets `calling_window` and the times the dashboard shows.
`start_at`	≤ 90 days ahead	next pass	Changeable only while the batch is `scheduled`.
`calling_window`	`{start, end, days}`	any hour, any day	`HH:MM` local times; `days` are ISO weekdays (1 = Monday).
`max_concurrency`	1–10	1	Calls in flight at once.
`max_attempts`	1–5	1	Attempts per recipient, including the first.
`retry_after_minutes`	5–1440	30	Wait after a failed attempt.
`dial_gap_seconds`	0–3600	0	Minimum seconds between starting two calls. Passes run every 30 seconds, so a call may start up to 30 s after its gap ends.
`dial_daily_cap`	object or null	null	Calls per local day, retries included.
`vars`	object	none	`{{vars.*}}` values for every call.

agent_version, agent_override, an inline agent or agent_team are also accepted; see Pinning a version. A window may cross midnight; days then names the evening it starts on: 21:00–06:00 with days: [5] runs Friday 21:00 to Saturday 06:00.

Daily cap and ramps

dial_daily_cap is {"kind": "fixed", "limit": 200} or a ramp, used to warm up a caller ID:

{ "kind": "ramp", "start": 10, "end": 50, "step": 1, "interval_days": 1 }

That places 10 calls a day, then 11, 12 … up to 50. start ≥ 1, end > start, step ≥ 1, interval_days 1–30. A ramp advances only on days the batch actually dialled (not on closed windows, weekends or pauses), keeps its progress when edited unless start changes, and is per batch.

Retries

Whether a recipient is retried depends on how the last attempt ended (last_close_reason on the recipient row).

Outcome	Retried
Completed — anyone answered, including a machine	Never. A reached number is never called twice.
Busy, no answer, temporarily unavailable, ring timeout	Yes, after `retry_after_minutes`, up to `max_attempts`.
Number not in service, or the person declined	No.
Carrier fault	Yes.
Configuration problem, platform fault, unrecognised ending	No.

A dial that could not be placed still spends an attempt.

Circuit breaker and credit

A batch stops itself after ten consecutive setup-style failures: carrier faults, configuration problems, platform faults, unmapped endings, and pass-level failures such as an unpublished agent, a deleted number or an account that is no longer ready. Any successful call resets the count. Busy and unanswered calls never count. On trip the batch becomes failed, failure_reason holds the last error, and unattempted recipients read as canceled. Running out of credit stops dialling without failing the batch. It stays running, spends no attempts, and failure_reason says the workspace is out of credits. It resumes on its own after a top-up.

A batch runs as its creator. Every pass re-authorizes as the user who created it. If they leave the workspace or drop below the editor role, each pass fails as a configuration problem and the breaker stops the batch. Re-create their campaigns under another account before they leave.

Pause, resume, cancel, edit, delete

Call	Allowed from	Effect
`POST /v1/calls/batches/{batch_id}/pause`	`scheduled`, `running`, `completed`	Stops claiming recipients. Live calls run to their end. Pausing a completed batch holds people you add later.
`POST .../resume`	`paused`	Continues. If `start_at` is still in the future it returns to `scheduled`.
`POST .../cancel`	`scheduled`, `running`, `paused`	Final. Everyone not yet called reads `canceled`; live calls finish.
`PATCH /v1/calls/batches/{batch_id}`	`scheduled`, `running`, `paused`, `completed`	Policy edits; the next pass reads them. `null` clears `calling_window`, `start_at`, `dial_daily_cap`. Never revisits anyone already called.
`DELETE /v1/calls/batches/{batch_id}`	`completed`, `canceled`, `failed`, no call in progress	Removes the batch and its recipient list. Its calls stay under Calls.

A disallowed transition is a 409 naming the current status.

curl -sS -X POST https://api.talqing.com/v1/calls/batches/2d5f7a91-4e63-4b08-9c17-8fa2e6b34d05/pause \
  -H "Authorization: Bearer $TALQING_API_KEY"

Add or remove recipients

POST /v1/calls/batches/{batch_id}/recipients appends up to 10,000 rows to any batch that is not canceled or failed; a completed batch goes back to running. Numbers the batch already holds, or repeated in the upload, are skipped and reported in skipped (row_number is the 1-based position in your request). The response is {added, skipped, total_recipients}.

curl -sS https://api.talqing.com/v1/calls/batches/2d5f7a91-4e63-4b08-9c17-8fa2e6b34d05/recipients \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": [{ "to": "+919812345678", "userdata": { "first_name": "Arjun" } }] }'

POST .../recipients/delete with recipient_ids removes rows that were never dialled; any other row comes back in rejected.

Watching a batch

GET /v1/calls/batches/{batch_id}:

{
  "status": "running",
  "counts": { "total": 4200, "pending": 3871, "dialing": 3, "completed": 302, "failed": 24, "canceled": 0, "voicemail": 11 },
  "dialed_today": 329,
  "dial_daily_cap_today": null,
  "next_dial_at": null,
  "next_dial_reason": null,
  "failure_reason": null
}

Field or call	Answers
`next_dial_at`, `next_dial_reason`	When it next dials and why it is waiting: `start`, `window` or `daily_cap`. Both null while dialling, paused or finished.
`dialed_today`, `dial_daily_cap_today`	Calls placed this local day against today’s limit.
`failure_reason`	Why it is not dialling, or why the breaker stopped it.
`GET .../recipients?status=failed`	Per person: `status`, `attempts`, `last_close_reason`, `last_close_reason_label`, `session_id` of the latest attempt.
`GET /v1/calls?batch_id=…`	The calls: transcripts, recordings, cost.
Webhooks `batch.started`, `batch.completed`, `batch.failed`	`batch.completed` fires again each time later additions are all handled. See webhooks.

Statuses

Batch status	Meaning
`scheduled`	Waiting for `start_at`.
`running`	Dialling, or waiting for its window or a free slot.
`paused`	Paused by someone. Live calls still finish.
`completed`	Everyone added so far was handled. Adding more resumes it.
`canceled`	Cancelled. Final.
`failed`	Stopped by the circuit breaker.

Recipient status	Meaning
`pending`	Not yet called, or waiting out `retry_after_minutes`.
`dialing`	A call is in flight. Keeps this status through a cancel.
`completed`	Reached. Terminal.
`failed`	Attempts spent, or the outcome was final.
`canceled`	Never attempted; the batch was cancelled or failed.

Pinning a version

Creating a batch with agent_version, agent_override, an inline agent or an agent_team freezes that cast at create, so a republish does not reach it. PATCHing agent_id clears the frozen cast and returns the batch to the current published version. The frozen plan is stored on every call, so attach FAQs by faq_id rather than inline. See per-call configuration.

Outbound lead qualification

A campaign end to end, from CSV to results.

Call analysis

Summaries, outcomes and structured fields across a batch.

Get started

Build

Guides

Create a batch

Fields

Daily cap and ramps

Retries

Circuit breaker and credit

Pause, resume, cancel, edit, delete

Add or remove recipients

Watching a batch

Statuses

Pinning a version

Next

Outbound lead qualification

Call analysis

​Create a batch

​Fields

​Daily cap and ramps

​Retries

​Circuit breaker and credit

​Pause, resume, cancel, edit, delete

​Add or remove recipients

​Watching a batch

​Statuses

​Pinning a version

​Next

Outbound lead qualification

Call analysis

Create a batch

Fields

Daily cap and ramps

Retries

Circuit breaker and credit

Pause, resume, cancel, edit, delete

Add or remove recipients

Watching a batch

Statuses

Pinning a version

Next