Batch Calling

Batch Calling lets you create large-scale outbound call campaigns using your AI agents. Upload a CSV of recipients, configure scheduling and concurrency, then let your agents handle each conversation.

Overview

Batch Calling provides enterprise-grade outbound calling capabilities:

CSV Upload - Upload recipients via CSV file with a downloadable template
Scheduling - Send now or schedule for a specific date and time
Call Windows - Restrict calls to specific hours and days of the week
Concurrency - Control how many calls run simultaneously
Draft & History - Save drafts and track all batch campaigns

Use Cases

Appointment reminders - Call patients/clients about upcoming appointments
Follow-up campaigns - Reach out to leads after an event or inquiry
Survey calls - Collect feedback from customers at scale
Notification calls - Inform contacts about important updates
Outreach campaigns - Introduce new products or services

How It Works

1. Create a Batch

Navigate to Batch Calls in the sidebar to access the feature. Fill in the batch configuration:

Batch Call Name - A descriptive name for your campaign
From Number - Select which Magpipe phone number to call from (shows associated agent)

2. Upload Recipients

Upload a CSV file with your recipient list. Download the template for the correct format:

name,phone_number
John Doe,+14155551234
Jane Smith,+12125559876

The CSV parser automatically detects columns including name, first_name, last_name, phone, phone_number, mobile, and cell.

Phone numbers should be in E.164 format (+1XXXXXXXXXX). Numbers without the + prefix will be auto-formatted.

3. Configure Scheduling

Send Now - Calls begin immediately after creation
Schedule - Pick a specific date and time to start the campaign

4. Set Call Window

Control when calls can be made:

Time Range - e.g., 9:00 AM to 5:00 PM
Days - Select which days of the week (default: Monday-Friday)

Calls outside the window are automatically paused and resume when the window reopens.

5. Concurrency Settings

Reserved Concurrency - Slots reserved for inbound and other calls
Batch Concurrency - Remaining slots allocated to batch calling

6. Send or Save Draft

Save as Draft - Save your batch to edit and send later
Send - Start the campaign (or schedule it)

7. Track Results

Switch to the History tab to view all batches with:

Status (draft, scheduled, running, completed, cancelled, failed)
Completion counts and failure counts
Click any batch to view individual recipient status updating in real-time
Re-run completed or failed batches with one click

Batch Status Flow

draft → scheduled → running → completed ↘
                  ↘ paused ↗              → re-run → running
                  ↘ cancelled            ↗
                  ↘ failed              ↗

recurring → paused → recurring (resumed)
         → cancelled
         → completed (max runs / end date)

Status	Description
`draft`	Saved but not sent
`scheduled`	Scheduled for future execution
`running`	Currently making calls
`paused`	Temporarily paused (outside call window or series paused)
`completed`	All recipients processed (or recurring series finished)
`cancelled`	Manually cancelled
`failed`	Batch encountered a critical error
`recurring`	Parent batch actively spawning child runs on schedule

Recipient Status

Each recipient’s status updates in real-time as the call progresses:

Status	UI Label	Description
`pending`	Pending	Waiting to be called
`calling`	Initiating	Call is being placed
`initiated`	Initiating	Call initiated with carrier
`ringing`	Ringing	Recipient’s phone is ringing
`in_progress`	Connected	Recipient answered, call in progress
`completed`	Hungup	Call completed successfully
`failed`	Failed	Call failed to connect
`busy`	Busy	Recipient’s line was busy
`no_answer`	No Answer	Recipient did not answer
`skipped`	Skipped	Skipped (batch cancelled)

Recurring Batches

Recurring batches repeat on a schedule — hourly, daily, weekly, or monthly. Each run calls ALL recipients again. This is useful for daily appointment reminders, recurring outreach campaigns, or weekly check-in calls.

How It Works

Recurring batches use a parent-child model:

Parent batch stores the recurrence config and recipients template. Status = recurring.
Child batch is an actual run, cloned from the parent. Has its own recipients and status tracking.
When a child completes, the system automatically spawns the next child scheduled for the next occurrence.

Setting Up Recurrence

In the Create view, configure the Repeat section:

Frequency — None, Hourly, Daily, Weekly, or Monthly
Interval — Every N units (e.g., every 2 days)
End Condition — Never, After N runs, or On a specific date

The existing call window (window_days + window_start_time/window_end_time) is still respected for each run.

Managing a Recurring Series

From the History view, click a recurring batch to see:

Recurrence config — frequency, interval, end condition
Run count — how many runs have completed
Runs list — all past and current runs (click to see recipient details)

Series controls:

Pause Series — stops new runs from spawning (active runs continue)
Resume Series — resumes spawning new runs
Cancel Series — cancels the parent and all scheduled/running children

Status Flow

recurring → paused → recurring (resumed)
         → cancelled
         → completed (max runs reached or end date passed)

API Example

await fetch('https://api.magpipe.ai/functions/v1/batch-calls', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'create',
    name: 'Daily Appointment Reminders',
    caller_id: '+16045551234',
    send_now: true,
    recurrence_type: 'daily',
    recurrence_interval: 1,
    recurrence_max_runs: 30,
    window_start_time: '09:00',
    window_end_time: '17:00',
    window_days: [1, 2, 3, 4, 5],
    recipients: [
      { name: 'John Doe', phone_number: '+14155551234' }
    ]
  })
});

To list child runs for a recurring parent:

await fetch('https://api.magpipe.ai/functions/v1/batch-calls', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({
    action: 'list_runs',
    parent_batch_id: '<parent-uuid>'
  })
});

Re-running Batches

Completed, cancelled, or failed batches can be re-run from the History view. Click the Re-Run button to reset all recipients back to pending and restart the campaign. This is useful for:

Retrying failed calls after fixing issues
Re-running campaigns with updated agent prompts
Reaching contacts who didn’t answer the first time

API Integration

You can create and manage batch calls programmatically via the API:

const response = await fetch('https://api.magpipe.ai/functions/v1/batch-calls', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'create',
    name: 'Appointment Reminders - January',
    caller_id: '+16045551234',
    send_now: true,
    window_start_time: '09:00',
    window_end_time: '17:00',
    window_days: [1, 2, 3, 4, 5],
    reserved_concurrency: 5,
    recipients: [
      { name: 'John Doe', phone_number: '+14155551234' },
      { name: 'Jane Smith', phone_number: '+12125559876' }
    ]
  })
});

See the Batch Calls API Reference for full details.

Best Practices

Contact Preparation

Verify phone numbers - Ensure all numbers are in E.164 format
Segment your list - Group contacts by campaign type
Check consent - Only call contacts who’ve opted in

Timing

Business hours - Use call windows to restrict calling hours
Time zones - Consider contact locations when setting windows
Scheduling - Schedule campaigns for optimal pickup rates

Agent Configuration

Make sure your outbound agent’s system prompt includes context about why you’re calling and what to achieve. Consider using outbound call templates for consistency.

Compliance

Ensure your batch calling campaigns comply with local regulations:

TCPA (US) - Requires prior express consent for automated calls
Do Not Call - Respect opt-out requests
Local laws - Check requirements in your jurisdiction

Limits

Limit	Value
Recipients per batch	Unlimited
Max concurrency	20
Cost per dial	$0.005

FAQ

Can I pause a running batch?

Yes, you can cancel a running batch from the History view. All pending recipients will be marked as skipped.

What happens outside the call window?

The batch processor automatically pauses when outside your configured call window and resumes when the window reopens.

Can I edit a batch after creation?

Only draft batches can be edited. Once a batch is scheduled or running, you can only cancel it.

How is billing handled?

Each dial costs $0.005 plus standard per-minute calling charges. Your credit balance is checked before each call.

What happens if my credits run out mid-batch?

The batch will pause when credits are insufficient. Add credits and restart the batch to continue.

How do recurring batches work?

Recurring batches use a parent-child model. The parent stores your config and recipients template. Each run creates a child batch that calls all recipients. When a run completes, the next one is automatically scheduled based on your frequency settings.

Can I pause a recurring series?

Yes, use the Pause Series button in the batch detail modal. Currently running calls will finish, but no new runs will start until you resume.

Get Started

Features

Guides

Overview

Use Cases

How It Works

1. Create a Batch

2. Upload Recipients

3. Configure Scheduling

4. Set Call Window

5. Concurrency Settings

6. Send or Save Draft

7. Track Results

Batch Status Flow

Recipient Status

Recurring Batches

How It Works

Setting Up Recurrence

Managing a Recurring Series

Status Flow

API Example

Re-running Batches

API Integration

Best Practices

Contact Preparation

Timing

Agent Configuration

Compliance

Limits

FAQ

Get Started

Features

Guides

​Overview

​Use Cases

​How It Works

​1. Create a Batch

​2. Upload Recipients

​3. Configure Scheduling

​4. Set Call Window

​5. Concurrency Settings

​6. Send or Save Draft

​7. Track Results

​Batch Status Flow

​Recipient Status

​Recurring Batches

​How It Works

​Setting Up Recurrence

​Managing a Recurring Series

​Status Flow

​API Example

​Re-running Batches

​API Integration

​Best Practices

​Contact Preparation

​Timing

​Agent Configuration

​Compliance

​Limits

​FAQ

Overview

Use Cases

How It Works

1. Create a Batch

2. Upload Recipients

3. Configure Scheduling

4. Set Call Window

5. Concurrency Settings

6. Send or Save Draft

7. Track Results

Batch Status Flow

Recipient Status

Recurring Batches

How It Works

Setting Up Recurrence

Managing a Recurring Series

Status Flow

API Example

Re-running Batches

API Integration

Best Practices

Contact Preparation

Timing

Agent Configuration

Compliance

Limits

FAQ