POST
Create Call Batch

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

A campaign: who to call, what runs, and when it may dial.

vars comes from AgentPlanRequest and is BATCH-level — one bag copied onto every call this campaign places. Per-person data is what a recipient's userdata is for.

​
from_phone_number_id
string<uuid>
required
​
name
string
required
Required string length: 1 - 200
​
recipients
BatchRecipientInput · object[]
required
Required array length: 1 - 10000 elements
​
timezone
string
required
​
agent
AgentConfig · object | null

A complete agent definition, run for this call and stored nowhere. Mutually exclusive with agent_id.

​
agent_id
string<uuid> | null

An agent in this workspace. Mutually exclusive with agent.

​
agent_override
AgentOverride · object | null

Changes layered on top of whichever base was named. Absent keys keep the base value, an explicit null clears the field, objects deep-merge and lists replace.

​
agent_team
AgentTeam · object | null

Run several agents on this call, defined here. Mutually exclusive with agent_id / agent / agent_version / agent_override.

​
agent_version

Which version of agent_id to run. Omit for the published one. "draft" runs the unpublished working copy — validated and tool-pinned at request time, and refused with the publish errors if it does not hold together.

​
calling_window
TimeWindow · object | null

The hours a list may run in, on the list's own clock.

Shared rather than duplicated, for the same reason window_state is: a call batch and an email send run store the same three values under the same names and must not each get their own copy of the rules. The field that carries one is named for what it gates — calling_window on a campaign, window on an email batch and its runs.

A window that crosses midnight (21:00-06:00) is valid and means exactly what an evening consumer-calling window means: the day check applies to the start side, so 21:00-06:00 on days: [5] runs Friday 21:00 through Saturday 06:00.

​
dial_daily_cap
FixedDailyCap · object

The same limit every day.

​
dial_gap_seconds
integer
default:0

Minimum seconds between STARTING two calls; 0 dials as slots free. A call may start up to 30 seconds after its gap ends.

Required range: 0 <= x <= 3600
​
max_attempts
integer
default:1
Required range: 1 <= x <= 5
​
max_concurrency
integer
default:1
Required range: 1 <= x <= 10
​
retry_after_minutes
integer
default:30
Required range: 5 <= x <= 1440
​
start_at
string<date-time> | null
​
vars
Vars · object | null

Values for the variables the agents on this session declare, read as {{vars.name}} in a prompt, a greeting and a tool. They override each agent's declared default and reach every agent the session runs, including a handoff target. Unlike userdata, which describes the PERSON and is kept on their contact record, these describe THIS session and are gone with it. Strings only; an empty string is a deliberate blank, not a request for the default. The model can see them, so credentials go in secrets (this session's own, where the request takes them) or a workspace secret, read as {{secrets.NAME}} by a tool.

Response

Successful Response

​
agent_id
string<uuid> | null
required
​
agent_name
string | null
required
​
calling_window
TimeWindow · object | null
required

The hours a list may run in, on the list's own clock.

Shared rather than duplicated, for the same reason window_state is: a call batch and an email send run store the same three values under the same names and must not each get their own copy of the rules. The field that carries one is named for what it gates — calling_window on a campaign, window on an email batch and its runs.

A window that crosses midnight (21:00-06:00) is valid and means exactly what an evening consumer-calling window means: the day check applies to the start side, so 21:00-06:00 on days: [5] runs Friday 21:00 through Saturday 06:00.

​
counts
CallBatchCounts · object
required
​
created_at
string<date-time>
required
​
dial_daily_cap
FixedDailyCap · object
required

The same limit every day.

​
dial_daily_cap_today
integer | null
required
​
dial_gap_seconds
integer
required
​
dialed_today
integer
required
​
ended_at
string<date-time> | null
required
​
failure_reason
string | null
required
​
from_e164
string | null
required
​
from_phone_number_id
string<uuid> | null
required
​
id
string<uuid>
required
​
max_attempts
integer
required
​
max_concurrency
integer
required
​
name
string
required
​
next_dial_at
string<date-time> | null
required
​
next_dial_reason
enum<string> | null
required
Available options:
start,
window,
daily_cap
​
retry_after_minutes
integer
required
​
start_at
string<date-time> | null
required
​
started_at
string<date-time> | null
required
​
status
enum<string>
required
Available options:
scheduled,
running,
paused,
completed,
canceled,
failed
​
timezone
string
required
​
agent_plan
StoredAgentPlan · object | null

What a call ran, frozen at the moment it started.

Written only when the call differs from "the published agent, as-is" — so a null agent_plan means exactly that. members[0] is the agent that answered.

​
vars
Vars · object | null