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
CallingWindow · object | null

The hours a batch may dial in, on the batch's own clock.

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.

​
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 put credentials in a workspace secret and read {{secrets.NAME}} from a tool instead.

Response

Successful Response

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

The hours a batch may dial in, on the batch's own clock.

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
​
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
​
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