Batch calls

A batch call dials a list of numbers from one of your phone numbers. Each row becomes a call with its own dynamic variables. The scheduler places calls as concurrency allows, only inside your call time window, and stops when every row has been dialled or you stop the batch.

Use batch calls for appointment reminders, reactivation campaigns, surveys and any list where you know the numbers up front.

Create a batch in the dashboard#

CSV format#

• The first row is the header.
• The first column is the phone number. Its header name does not matter.
• Every other column becomes a dynamic variable. Header names are lower-cased and anything other than letters, digits and _ becomes _ (so First Name becomes {{first_name}}).
• Spaces, brackets and dashes in the phone number are removed. Australian numbers written as 0412345678 (10 digits starting 02, 03, 04, 07 or 08) are converted to +61412345678.
• Rows whose number is not E.164 after that are skipped.

The downloadable template:

phone number,first_name,appointment_time
+61412345678,Sam,Tuesday 3pm
+61498765432,Priya,Wednesday 10am

Use the variables in the agent's prompt or begin message, for example Hi {{first_name}}, I'm calling about your appointment on {{appointment_time}}.

Create a batch with the API#

POST /create-batch-call takes the recipients as tasks. CSV parsing is a dashboard feature; the API expects the rows already parsed.

curl -X POST https://api.tried.com.au/create-batch-call \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October reactivation",
    "from_number": "+61255501234",
    "tasks": [
      { "to_number": "+61412345678", "retell_llm_dynamic_variables": { "first_name": "Sam" } },
      { "to_number": "+61498765432", "retell_llm_dynamic_variables": { "first_name": "Priya" } }
    ],
    "trigger_timestamp": 1792000000000,
    "reserved_concurrency": 2,
    "honor_internal_dnc": true,
    "call_time_window": {
      "windows": [{ "start": 540, "end": 1020 }],
      "timezone": "Australia/Sydney",
      "day": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
    }
  }'

BatchTask fields:

Every task needs an agent: either the number has outbound_agents, or the task has override_agent_id. Otherwise the request returns 400.

Call time window#

The dashboard offers one window with these timezones: Australia/Sydney, Australia/Melbourne, Australia/Brisbane, Australia/Adelaide, Australia/Perth, Pacific/Auckland, America/New_York, America/Chicago, America/Los_Angeles, Europe/London and UTC. The API accepts several windows and any IANA name.

How the scheduler dials#

A scheduler pass runs every 5 seconds (BATCH_TICK_MS). For each batch that is planned or ongoing and whose scheduled time has passed:

1. If the current time is outside call_time_window, the batch waits.
2. Free capacity is the workspace concurrency limit minus reserved_concurrency minus calls already in progress.
3. Pending tasks are dialled in order, up to that capacity, through the same path as POST /v2/create-phone-call (including the number's calls-per-second limit and allowed outbound countries).
4. When no pending tasks remain, the batch becomes sent.

A task that cannot be dialled is marked failed with the error. When the credit balance runs out, the task gets a not_connected call with disconnection_reason: "no_valid_payment" so the attempt shows in Call History.

Statuses and counters#

The batch list shows Recipients, Sent, Picked up and Successful, with a progress bar of sent over recipients.

• Sent counts dial attempts.
• Picked up counts calls that connected. The percentage is picked up over sent.
• Successful counts calls whose post-call analysis set call_successful to true. The percentage is successful over picked up.

Click a row to open the drawer. View calls in Call History filters Call History to the batch. With the API, filter POST /v2/list-calls by filter_criteria.batch_call_id.

Start, stop and delete#

Cost#

Batch calls are billed at the same per-minute rate as other calls, plus $0.01 for every dial attempt (batch_dial).

Limits and gotchas#

• Batch calls count against the workspace concurrency limit and leave reserved inbound slots free. See Concurrency.
• Reserved concurrency in the dashboard accepts 0 to 50.
• The call time window is evaluated in the window's timezone, not each recipient's own timezone. Split a list by region if recipients span timezones.
• trigger_timestamp in the past starts the batch on the next scheduler pass.
• Dialling needs LiveKit SIP. Needs keys

Related#

• Outbound calls
• Create batch call API