Skip to main content

​
Introduction

Batch calls let you run high-volume call campaigns by uploading a list of recipients as a CSV. One agent staffs every call in the batch, and you monitor progress and results from the dashboard. Common use cases include:

Outbound Campaigns

Reach customers with limited-time offers or updates.

Customer Reminders

Follow up with clients for appointments, payments, or check-ins.

Lead Qualification

Qualify or re-engage leads from your CRM or sign-up funnel.

Data Collection

Prompt users for updated contact info, preferences, or survey responses.

​
Creating a Batch Call

Batches live under Dispatch in the dashboard sidebar. At All agents you choose the agent. Inside an agent, that agent is filled in and locked. To start a batch call:
  1. Open Batches under Dispatch and press Create Batch in the top bar.
  2. Recipients: upload your CSV.
  3. Script: pick the agent that staffs the batch and write the instructions for this run.
  4. Review & send: check the first recipient as the agent will get them, name the batch, and press Start calling.
See Run a batch for the full wizard. Batch calls are built around a CSV file containing all information on your recipients, with each row representing a single recipient.

​
Required Fields

Your uploaded CSV must include a column named phone_number, in exactly that spelling. Every number needs a country code: +14155550100 works, 4155550100 does not. Additional columns can be included to define dynamic variables referenced during the call.
Important: Column names cannot contain spaces since they are used as variables. Use underscores or camelCase instead (for example, customer_name or customerName, not customer name).
Example format: With this CSV, we are aiming to send 2 calls out in our batch, to +12345678909 and +10987654321. In each of those calls, the agent can use the information in the other columns (business_name, previous_customer, champion_name), similar to request data in a normal call. The webhook column matches a call setting name, so check how it is mapped (see Watch the defaults below). On the Script step, under How your columns are used, each column gets a dropdown. Use as {{column}} makes the value available in the prompt as {{column_name}}.
Watch the defaults: a column named after a call setting, like from or voice, defaults to setting that field per call rather than becoming a variable. Rename the column if you meant it as a variable.
When you create a batch through the API, each entry in call_objects follows the same schema as /v1/calls, so pass per-recipient values in that entry’s request_data.

​
Monitoring Batch Progress

You can monitor batch progress in two ways: polling the batch and logs endpoints, or receiving status webhooks when using the API.

​
Status webhook (API)

When creating a batch via the API, you can pass an optional status_webhook URL. We will send HTTP POST requests to that URL at each major lifecycle step and when the batch finishes, so you get push updates without polling. When we call it: We POST once per phase: validating → dispatching → in_progress (or in_progress_chunked for large batches) → optionally waiting_for_scheduled_calls → then one final event: completed, failed, or completed_partial. Each request is JSON with batch_id, status, and timestamp; final events include call counts or error code and reason when applicable. Best practice: Your endpoint should respond with 200 within a few seconds. Do any heavy processing asynchronously so the batch workflow is not delayed (we wait up to 10 seconds per webhook call). See the Create Batch API reference for the full payload shape and example bodies.

​
Dashboard and polling

After launching a batch, return to Batches under Dispatch. Each batch is listed with its Status, Name, Batch ID, and Created time, newest first with active batches on top. Each row has two icon buttons. The first opens Conversations filtered to that batch. The second stops the calls that have not been placed yet, and asks first. Select a row for a detail panel with the event log and its own Stop Batch button, which stops the batch without asking.

​
Understanding Batch Statuses

Your batch will progress through various statuses as it processes. Here’s what each status means:
  • Initializing - The batch is being set up and prepared for processing. This happens immediately after creation.
  • Validating - The system is verifying your CSV format, phone numbers, and call parameters before dispatching.
  • Dispatching - Calls are being actively sent out to recipients from your CSV.
  • In Progress - Calls are actively being processed and conversations are ongoing.
  • In Progress (Chunked) - Large batches are being processed in smaller chunks for better performance.
  • Waiting for Scheduled Calls - The batch is waiting for calls with specific start times to be executed.
  • Unknown - In the dashboard list, a batch past its first thousand calls that is still running. Use Stop Batch in the detail panel to stop it.
  • Completed - All calls in the batch were successfully processed and finished.
  • Completed Partial - The batch ended early, usually because you stopped it. Check the logs for details.
  • Failed - The batch ended on an error. Review the error logs for troubleshooting.

​
Example Use Case

Let’s say you’re running a follow-up campaign for returning customers. Upload a CSV like: Then write the instructions on the Script step:
The agent personalizes each call using the values from that row in your CSV.

​
Frequently Asked Questions

A CSV with one bad row is rejected whole. The upload checks every number before the batch exists, names up to three of the bad rows, and counts the rest. Duplicates and numbers on your do-not-call list are different: those are dropped at dial time and the rest of the batch runs.
Yes. The agent that staffs the batch brings its own configuration, including its tools.
Use the first icon button on the batch’s row to open Conversations filtered to that batch, then open each call’s transcript and details.
You can use our API to send a batch call. See our API Reference for more details.
Docs for agents: llms.txt