> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch calls: call a list of people with your agent

> Upload a list of recipients and let your agent call them: schedule, calling days and hours, concurrency, automatic retries, statuses and results.

A batch call has your agent call everyone on a list, from one of your numbers. You upload a CSV or Excel file of recipients, choose when calls may go out and how many run at once, and Hamsa works through the list, retrying calls that fail. Each recipient's columns become variables, so the agent can greet people by name or mention their order.

## Before you start

* A phone number in the project with a working outbound connection. See [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md).
* An agent to make the calls.
* A recipient file. See [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md).
* Owner or Admin role. Members can see batch calls but can't create, change or stop them.

## Create a batch call

In the sidebar, open **Telephony** > **Batch calls** and click **Create**. The form **Create a batch call** opens.

**1. Basic information**

* **Batch call name**: up to 100 characters, for example "September renewal reminders".
* **From number**: the number the calls come from.
* **Voice agent**: the agent that talks to recipients.

Both lists show every number and agent in the project. A number that can't dial out fails when the calls start, not here.

![The Create a batch call form: Basic information with a name, the Main support line as From number, Support Concierge as Voice agent, and 120 recipients added](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-create-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=9e196a4531227e29ac0f89a2c2454109)

**2. Upload recipients**

Under **Upload recipients**, click **Download Excel template** or **Download CSV template** if you need a starting point. Then choose your file or drag it in. **Upload validation results** opens with **Accepted** and **Rejected** rows.

Fix a rejected row with **Edit**, then click **Add to accepted** once it's valid. Click **Add accepted rows** to keep the accepted rows. Rows you don't fix are dropped.

![Upload validation results: 21 accepted and 2 rejected rows, the accepted rows with their columns, and Add accepted rows](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-upload-validation-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=1522fa3763b82269dee92adcfc144dd9)

**3. Review the recipients**

The form says "You have added 120 recipients" (your count). Click **View recipients** to open **Manage recipients**: every recipient with **Phone number**, **Name**, **Ignore E.164 validation** and **External params**, 30 to a page. Remove a recipient with the cross at the end of its row, then click **Save** (it shows how many recipients remain). **Cancel** with removals you haven't saved asks first: **Discard changes** throws them away.

![The recipients card: You have added 120 recipients, with View recipients and Upload another file](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-recipients-added-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=77a30ac64f65f14df546c203edc8cfe2)

![Manage recipients: phone numbers, names, Ignore E.164 validation and External params for each recipient, a remove button per row, and Save 119 after one removal](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-manage-recipients-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=63fedb08545373910d09049c4006d1af)

To add recipients, fix your file and click **Upload another file**. "Replace existing recipients?" warns that a new file replaces every recipient you added.

**4. When to send the calls**

Pick **Send now** or **Schedule**, and the **Timezone** (your computer's time zone by default). For **Schedule**, choose **Select date and time**: the date and time are in that **Timezone**, and must be at least a minute ahead.

**5. When calls can run**

Set the **Time range** (start and end, in 15 minute steps) and the **Days of week**. Calls only go out inside this window. The default is 09:00 to 17:00, Sunday to Thursday.

![The calling window editor: Time range 09:00 to 17:00 and Sunday to Thursday ticked under Days of week](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-calling-window-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=fcccc2a2710a9c3d23ea138b8fba0aa4)

**6. Concurrency for this batch call**

Set how many calls this batch call can make at the same time. The default is 1. The card compares this batch call's concurrency with your plan's limit: "Using 2 of 5 total (3 remaining)". It doesn't count other active batch calls, which are checked when you save (see below).

**7. Save**

Click **Save**. The toast says "Batch call created" and the batch call shows as **Scheduled**.

![The rest of the form: Schedule on 1 November 2026 in Asia/Dubai, calls from 09:00 to 17:00 Sunday to Thursday, and concurrency 2 with Using 2 of 10 total](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-create-schedule-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=9a4ac30ac713c73cd6ea7e8503986712)

You can only have one unsaved batch call open at a time. It isn't saved as a draft: leaving the page asks **Discard batch call draft?**

## When calls go out

Hamsa checks the list about once a minute. On each check, for each batch call that is due:

1. If today isn't one of the **Days of week**, or the time is outside the **Time range**, nobody is called. Recipients wait for the next allowed window.
2. Otherwise Hamsa starts as many calls as this batch call has free slots, up to its concurrency.
3. Recipients who haven't been tried yet go first, then retries that are due.

The window is read in the batch call's **Timezone**. A recipient with a `timezone` column is called inside the window in their own time zone. See [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md#time-zones).

The batch call's **Timezone** decides both the start time and the calling window, for **Send now** and **Schedule** alike.

## Concurrency

Your plan sets how many calls can run at the same time. The limit belongs to the owner's account, so it's shared by every project the owner has. See [Billing](https://docs.tryhamsa.com/overview/billing.md#concurrent-calls). Every batch call reserves part of it with its own concurrency, from the moment you save it until it finishes.

* When you save, the concurrency of this batch call plus every **Scheduled**, **In progress** and **Paused** batch call in all of the owner's projects must fit in the plan's limit. If it doesn't, saving fails with "Reserved concurrency exceeds your voice agent concurrency limit".
* To free some up, wait for a batch call to finish, cancel one, or lower this one's number.
* While it runs, a batch call never has more calls on the line than its concurrency.

## Statuses

A batch call has one of these statuses:

| Status | What it means |
| - | - |
| **Scheduled** | Saved and waiting for its start time. A **Send now** batch call is Scheduled for up to a minute before it starts. |
| **In progress** | Calling. Calls only go out inside the calling window. |
| **Paused** | Stopped by you. No new calls start until you resume. |
| **Completed** | Nobody is left to call and no retry is due. This includes a batch call in which every call failed. |
| **Cancelled** | Stopped for good. Recipients not yet called are **Cancelled**. |

Each recipient has one of these:

| Status | What it means |
| - | - |
| **Pending** | Not called yet. |
| **Queued** | Picked for the next call. |
| **In progress** | On the line, or ringing. |
| **Completed** | The person answered and the call ended. |
| **No answer** | Nobody answered, the line was busy, or the call was declined. |
| **Failed** | The call couldn't be placed or didn't finish. If attempts are left, **Next try** shows when it's tried again. |
| **Cancelled** | The batch call was cancelled before this recipient was called. |

## Retries

A failed call is retried on its own:

* Up to 3 attempts per recipient: the first call, then a retry after 10 minutes, then one after another 20 minutes.
* Only **Failed** calls are retried automatically. **No answer** is final until you retry the batch call yourself.
* A call that never reports an end is counted as failed after 90 minutes.
* Retries still wait for the calling window.

The recipients table shows **Attempts** (for example 1/3), **Last attempt** and **Next try**.

## Manage a batch call

Open a batch call from the list. The buttons in its header depend on the status:

| Button | Shown when | What it does |
| - | - | - |
| Reload icon | Always | Refreshes the data: "Batch call data refreshed". |
| **Pause** | In progress | Stops new calls. Recipients waiting in the queue go back to Pending. |
| **Resume** | Paused | Starts calling again, straight away. |
| **Retry** | Completed, with at least one Failed or No answer recipient | Sets Failed and No answer recipients back to Pending with 0 attempts, and schedules the batch call again. |
| **Restart** | Cancelled | Like Retry, and also calls the recipients that were Cancelled. |
| **Cancel** | Scheduled, In progress or Paused | Stops the batch call for good. Asks first: "Cancel this batch call? This can't be undone." |
| **Delete** | Always | Removes the batch call from the list, with **Undo** for a few seconds. An unfinished batch call is cancelled first. Its calls stay in the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md). |

To rename a batch call, click the pencil next to its name. Nothing else can change after you save: to change the list, number, agent or window, create a new batch call.

Pausing or cancelling doesn't hang up calls already on the line.

The open batch call refreshes every 30 seconds while it's Scheduled or In progress.

## Follow the results

The summary at the top of a batch call shows:

* "84 of 120 recipients done" and how many are still to call.
* A bar of recipient statuses. Click a status in the legend to filter the list, and **Show all** to clear it.
* **Calls ended per hour** (or per day for longer batch calls).
* The setup in one line: from number, calling days and hours with the time zone, and "2 calls at once".
* **Details**: **Type**, **Started**, **When calls can run**, **Timezone** and **Concurrency for this batch call**.

![An in-progress batch call: 84 of 120 recipients done, the status legend, Calls ended per hour, the setup line, and All recipients with Attempts and Last attempt](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-in-progress-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=1cc083f6d4618ef93c772c187224a4bd)

Below it, **All recipients** lists each recipient with **Phone number**, **Name**, **Ignore E.164 validation**, **External params**, **Status**, **Attempts**, **Last attempt** and **Next try**. Hover a status to see the last error. Click a **Completed** or **Failed** row to open its call, with the transcript and outcome. See [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md).

![The recipients filtered to Failed: four recipients with 1/3 or 2/3 attempts and their last attempt, and Show all](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/batch-call-recipients-failed-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=6b29818dc71f9530644477451d0d1906)

While a batch call runs, the **Activity** tray in the header lists it. When it ends you get "Batch call finished", "Batch call finished with errors" or "Batch call failed". Turn on **Notify me when something finishes** for a browser notification.

To get each call's result in your own system, set up a [webhook](https://docs.tryhamsa.com/agents/connect/webhooks.md) on the agent. Each call in a batch sends its own events.

## Which agent and values a call gets

* The **Voice agent** you picked talks to the recipient.
* Batch calls run what prod runs. If prod runs an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md), the recipient's number decides the version.
* Each recipient's columns become variables for that call. See [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md).
* The default values, default parameters and the model check come from the batch call's own agent. The **From number** only supplies the line and the caller ID, so it doesn't matter which agent it's assigned to, or whether it has one.

## Create a batch call with the API

Send the recipients as JSON. Use a secret key on your server; with **Limited** access, the quick select **Manage outbound call campaigns** covers these requests.

```bash theme={null}
curl -X POST https://api.tryhamsa.com/v1/voice-agents/campaigns \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "September renewal reminders",
    "phoneNumber": "+14155550100",
    "voiceAgentId": "8c1d2f3a-5b6e-4c7d-9e8f-0a1b2c3d4e5f",
    "sendType": "SCHEDULED",
    "scheduledDate": "2026-11-02T06:00:00.000Z",
    "scheduledTimezone": "Asia/Dubai",
    "timeRange": {
      "days": ["SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY"],
      "startCallingTime": "09:00",
      "endCallingTime": "17:00"
    },
    "reservedConcurrency": 2,
    "recipients": [
      { "phoneNumber": "+971501234567", "customer_name": "Sara", "renewal_date": "15 November" },
      { "phoneNumber": "+971509876543", "customer_name": "Omar", "renewal_date": "20 November" }
    ]
  }'
```

| Field | Required | What it does |
| - | - | - |
| `name` | Yes | 1 to 100 characters. |
| `phoneNumber` | Yes | Your Hamsa number to call from, as listed on the phone numbers page. |
| `voiceAgentId` | Yes | The agent that makes the calls. Must be in the key's project. |
| `sendType` | Yes | `NOW` or `SCHEDULED`. |
| `scheduledDate` | With `SCHEDULED` | Start time, ISO 8601, for example `2026-11-02T06:00:00.000Z`. |
| `scheduledTimezone` | With `SCHEDULED` | IANA time zone for the calling window, for example `Asia/Dubai`. Send it with `NOW` too: without it, the window is read in UTC. |
| `timeRange` | Yes | `days` (at least one of `MONDAY` to `SUNDAY`), `startCallingTime` and `endCallingTime` as `HH:mm`. Start must be before end. |
| `reservedConcurrency` | No | Calls at once for this batch call. Default 1. |
| `recipients` | Yes | At least one. Each has `phoneNumber`, and optionally `name`, `ignoreE164Validation` and any other keys, which become variables. |

The response has the new batch call's `id` and `status` (`SCHEDULED`). Other requests on `/v1/voice-agents/campaigns`:

| Request | What it does |
| - | - |
| `GET /v1/voice-agents/campaigns` | List batch calls, newest first. |
| `GET /v1/voice-agents/campaigns/{id}` | One batch call with its recipients. |
| `PATCH /v1/voice-agents/campaigns/{id}` | Rename it. |
| `POST /v1/voice-agents/campaigns/{id}/pause` | Pause it. |
| `POST /v1/voice-agents/campaigns/{id}/resume` | Resume it. |
| `POST /v1/voice-agents/campaigns/{id}/retry` | Retry a completed batch call, or restart a cancelled one. |
| `POST /v1/voice-agents/campaigns/{id}/cancel` | Cancel it. |
| `DELETE /v1/voice-agents/campaigns/{id}` | Delete it. |

## Good to know

* There's no export of results. Use the agent's [webhook](https://docs.tryhamsa.com/agents/connect/webhooks.md), or open each call from the recipients table.
* Search in the batch calls list matches the name or the ID.
* The list doesn't refresh on its own. The open batch call does.
* Resuming a paused batch call starts calling at once, even if it was scheduled for later.

## Related

> [card] [Batch call recipient file](https://docs.tryhamsa.com/agents/connect/batch-call-file.md)
>
> Columns, phone number rules and time zones.

> [card] [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md)
>
> Get each call's transcript and outcome.

> [card] [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md)
>
> Use recipient columns in your prompt.

> [card] [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md)
>
> Manage the numbers your batch calls come from.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.