Automate and schedule calls using Batches

What is Batch Calling?

Batch calling lets you automate outbound calls to hundreds or thousands of contacts by uploading a CSV file with phone numbers and custom data. Ideal for lead qualification, customer outreach, appointment reminders, and other high-volume calling campaigns.

CSV File Format

Your CSV file must follow these rules:

Use E.164 Phone Format

All phone numbers must include the country prefix in E.164 format (e.g., +11231237890).

Use contact_number Header

The phone number column must use contact_number as the header.

Add Custom Variables

Include any additional variables (name, address, etc.) as separate columns. These are passed to the agent as context.

example_batch_file.csv

contact_number,first_name,last_name
+11231237890,Bruce,Wayne
+91012345678,Bruce,Lee
+00021000000,Satoshi,Nakamoto
+44999999007,James,Bond

In Excel, typing + at the beginning of a cell is interpreted as a formula. Add an apostrophe (') before the plus sign to retain it.

Download an example CSV file

Only the contact_number column is validated for correctness. Other columns (custom variables like first_name, address, etc.) are passed through as-is without any validation.

Using the Dashboard

You can upload batches, schedule them, and configure auto-retry directly from the Bolna dashboard.

Open the Batches Tab

Navigate to your agent → Batches tab. You’ll see a list of all your past batches along with their status, execution details, and actions like Run Now, Stop, Download, and Delete.Click Upload Batch to get started.

Agent Batches list — Agent Batches overview showing batch status, execution details, and available actions

Upload Your CSV

Drag and drop your CSV file or click to browse. After uploading, you’ll see how many rows were parsed and how many contacts have valid phone numbers.

Upload Batch dialog with CSV upload, phone number selection, scheduling, and webhook options

In this dialog you can:

Select a phone number to make calls from (Bolna managed or your own)
Choose to Run Now or Schedule the batch for a future date and time
Enable auto-retry for failed calls
Set a webhook URL to receive real-time call status updates

Schedule or Run Now

Select Run Now to start calls immediately, or click Schedule to pick a future date and time. Use the quick-select buttons to schedule 10 minutes, 30 minutes, or 1 hour from now.

Schedule batch options — Scheduling options with Run Now, Schedule, and quick-select time buttons

Configure Auto-Retry (Optional)

Enable Auto-retry failed calls to automatically re-attempt calls that didn’t connect. You can configure:

Retry on: Select which call outcomes trigger a retry (No Answer, Busy, Failed, Error, Voicemail)
Maximum retry attempts: Set up to 3 retry attempts per contact
Retry intervals: Define increasing delays between attempts (e.g., 30 min, 60 min, 120 min)

Auto-retry configuration — Auto-retry settings with retry conditions, max attempts, and configurable intervals

Click Upload this batch to confirm. Your batch will appear in the batches list with its scheduled time and status.

Webhook Notifications

You can provide a Webhook URL in the upload dialog to receive real-time updates as each call in the batch completes. Bolna sends a POST request to your webhook endpoint with the call’s execution data, including the call status, transcript, extracted data, and cost breakdown. This is useful for syncing call results to your CRM, triggering follow-up workflows, or logging outcomes in real time without polling the API.

If you don’t set a webhook, you can still retrieve all results later using the List Batch Executions API.

Using the Batch API

Create a Batch

Upload your CSV file using the Create Batch API:

curl --location 'https://api.bolna.ai/batches' \
--header 'Authorization: Bearer <api_key>' \
--form 'agent_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"' \
--form 'file=@"/my-first-batch.csv"' \
--form 'from_phone_numbers="+919876543210"' \
--form 'from_phone_numbers="+919876543211"'

{
    "batch_id": "abcdefghijklmnopqrstuvwxyz012345",
    "state": "created"
}

Schedule the Batch

Use the batch_id to schedule via the Schedule Batch API. The date and time must be in ISO 8601 format with timezone:

curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/schedule' \
--header 'Authorization: Bearer <api_key>' \
--form 'scheduled_at="2024-03-20T04:05:00+00:00"'

{
    "message": "success",
    "state": "scheduled at 2024-03-20T04:10:00+00:00"
}

Check Batch Status

Monitor progress using the Get Batch API:

curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345' \
--header 'Authorization: Bearer <api_key>'

{
    "batch_id": "abcdefghijklmnopqrstuvwxyz012345",
    "humanized_created_at": "19 minutes ago",
    "created_at": "2024-03-13T14:12:50.596315",
    "updated_at": "2024-03-13T14:19:13.115411",
    "status": "scheduled",
    "scheduled_at": "2024-03-20T04:10:00+05:30"
}

Retrieve Executions

After the batch completes, fetch all execution results using the List Batch Executions API:

curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/executions' \
--header 'Authorization: Bearer <api_key>'

[
  {
    "id": 7432382142914,
    "conversation_duration": 123,
    "total_cost": 123,
    "transcript": "<string>",
    "createdAt": "2024-01-23T01:14:37Z",
    "updatedAt": "2024-01-29T18:31:22Z",
    "usage_breakdown": {
      "synthesizerCharacters": 123,
      "synthesizerModel": "polly",
      "transcriberDuration": 123,
      "transcriberModel": "deepgram",
      "llmTokens": 123,
      "llmModel": {
        "gpt-3.5-turbo-16k": {
          "output": 28,
          "input": 1826
        }
      }
    }
  }
]

Complete Example

Python script using all Batch APIs together

batch_script.py

import asyncio
import os
from dotenv import load_dotenv
import aiohttp

# Load environment variables from .env file
load_dotenv()

# Load from .env
host = "https://api.bolna.ai"
api_key = os.getenv("api_key", None)
agent_id = 'ee153a6c-19f8-3a61-989a-9146a31c7834'  # Agent to create batch for
file_path = '/path/of/csv/file'
schedule_time = '2024-06-01T04:10:00+05:30'
from_phone_numbers = ['+919876543210', '+919876543211']


async def schedule_batch(api_key, batch_id, scheduled_at):
    print("Scheduling batch for batch_id: {}".format(batch_id))
    url = f"{host}/batches/{batch_id}/schedule"
    headers = {'Authorization': f'Bearer {api_key}'}
    data = {'scheduled_at': scheduled_at}

    try:
        async with aiohttp.ClientSession() as session:
            async with session.post(url, headers=headers, data=data) as response:
                response_data = await response.json()
                if response.status == 200:
                    return response_data
                else:
                    raise Exception(f"Error scheduling batch: {response_data}")
    except aiohttp.ClientError as e:
        print(f"HTTP Client Error: {str(e)}")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")


async def get_batch_status(api_key, batch_id):
    print("Getting batch status for batch_id: {}".format(batch_id))
    url = f"{host}/batches/{batch_id}"
    headers = {'Authorization': f'Bearer {api_key}'}

    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, headers=headers) as response:
                response_data = await response.json()
                if response.status == 200:
                    return response_data
                else:
                    raise Exception(f"Error getting batch status: {response_data}")
    except aiohttp.ClientError as e:
        print(f"HTTP Client Error: {str(e)}")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")


async def get_batch_executions(api_key, batch_id):
    print("Getting batch executions for batch_id: {}".format(batch_id))
    url = f"{host}/batches/{batch_id}/executions"
    headers = {'Authorization': f'Bearer {api_key}'}

    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, headers=headers) as response:
                response_data = await response.json()
                if response.status == 200:
                    return response_data
                else:
                    raise Exception(f"Error getting batch executions: {response_data}")
    except aiohttp.ClientError as e:
        print(f"HTTP Client Error: {str(e)}")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")


async def create_batch():
    url = f"{host}/batches"
    headers = {'Authorization': f'Bearer {api_key}'}

    with open(file_path, 'rb') as f:
        form_data = aiohttp.FormData()
        form_data.add_field('agent_id', agent_id)
        form_data.add_field('file', f, filename=os.path.basename(file_path))

        # Add multiple from_phone_numbers
        for phone in from_phone_numbers:
            form_data.add_field('from_phone_numbers', phone)

        async with aiohttp.ClientSession() as session:
            async with session.post(url, headers=headers, data=form_data) as response:
                response_data = await response.json()
                if response_data.get('state') == 'created':
                    batch_id = response_data.get('batch_id')
                    res = await schedule_batch(api_key, batch_id, scheduled_at=schedule_time)
                    if res.get('state') == 'scheduled':
                        check = True
                        while check:
                            # Check status every 1 minute
                            await asyncio.sleep(60)
                            res = await get_batch_status(api_key, batch_id)
                            if res.get('status') == 'completed':
                                check = False
                                break
                    if not check:
                        res = await get_batch_executions(api_key, batch_id)
                        print(res)
                        return res


if __name__ == "__main__":
    asyncio.run(create_batch())

Next Steps

Concurrency Limits

Understand outbound calling concurrency limits

Buy Phone Numbers

Set up dedicated phone numbers for campaigns

Context Variables

Personalize each call with dynamic data

Auto-Retry

Automatically retry failed calls

Quickstarts

Phone Numbers & Calling Setup

Outbound Calling

Inbound Calling

Managing Live Calls

Prompting & Personalization

Tools & Function Calling

Post-Call & Analytics

No-Code & Automation

SIP Trunking Guide

Integrations

Automate and schedule calls using Batches

What is Batch Calling?

CSV File Format

Using the Dashboard

Webhook Notifications

Using the Batch API

Complete Example

Next Steps

Concurrency Limits

Buy Phone Numbers

Context Variables

Auto-Retry

​What is Batch Calling?

​CSV File Format

​Using the Dashboard

​Webhook Notifications

​Using the Batch API

​Complete Example

​Next Steps

Concurrency Limits

Buy Phone Numbers

Context Variables

Auto-Retry

What is Batch Calling?

CSV File Format

Using the Dashboard

Webhook Notifications

Using the Batch API

Complete Example

Next Steps