Batch Calling - TalkifAI

Overview

TalkifAI Batch Calling lets you run large-scale automated outbound call campaigns. Upload a CSV with contacts, select an agent, and the system automatically calls all contacts using your voice agent. Best for:

Payment collection reminders
Appointment confirmations
Customer satisfaction surveys
Lead follow-ups
Renewal notifications
Event reminders

Scale: Supports up to 10,000 contacts per batch with automatic retry and concurrency control.

How It Works

1. Upload CSV with contacts
         │
         ▼
2. Validate CSV format & phone numbers
         │
         ▼
3. Configure batch settings
   - Select agent
   - Set concurrency limit
   - Schedule start time (optional)
         │
         ▼
4. Batch job created → Stored in Redis queue
         │
         ▼
5. ARQ Worker picks up jobs
         │
         ├── Check org concurrency (default: 5)
         ├── Check batch concurrency (default: 5)
         │
         ▼
6. For each contact:
   - Initiate outbound call
   - Agent handles conversation
   - Mark status (completed/failed)
   - Retry on failure (up to 3 times)
         │
         ▼
7. Batch completes → Analytics available

URL: /batch-calls Access: Studio → Batch Calls (sidebar)

Permission Required: Owners and Admins can create batch jobs. Members can view batches in their organization.

UI Overview

The Batch Calls page has two tabs:

Tab 1: Create New

CSV file upload
Batch configuration form
Scheduling options

Tab 2: Your Batches

List of all batch campaigns
Status filtering
Search and pagination
Batch actions (view, pause, resume, cancel, delete)

Creating a Batch Campaign

Step 1: Navigate to Batch Calls

Go to Studio → Batch Calls (sidebar)
Click Create New tab (default)

Step 2: Upload CSV File

CSV Requirements:

Requirement	Details
File Format	CSV (.csv extension)
Required Column	`phone` (case-insensitive: Phone, PHONE, phone)
Phone Format	E.164 format (+12025550123)
Optional Columns	`name`, `email`, custom fields
Max Contacts	10,000 per batch
File Size	Max 10MB

CSV Template:

phone,name,email,custom_field_1
+12025550101,John Smith,john@example.com,VIP
+12025550102,Jane Doe,jane@example.com,Premium
+12025550103,Bob Wilson,bob@example.com,Standard

Upload Process:

Click Upload CSV button or drag & drop file
System validates:
- File type (.csv)
- Required phone column
- Phone number format
- Duplicate detection
- Empty rows
Shows validation report:
- ✅ Total rows
- ✅ Valid rows
- ⚠️ Invalid rows (with reasons)
- ⚠️ Duplicate phones

Validation Checks:

Check	Description
Format Check	Verifies CSV structure
Phone Validation	Checks E.164 format
Duplicate Detection	Identifies duplicate numbers
Empty Row Check	Removes blank rows
Header Detection	Auto-detects headers

Step 3: Configure Batch Settings

Form Fields:

Field	Required	Description
Batch Name	✅	Descriptive name (e.g., “January Payment Reminders”)
Description	❌	Internal notes about the campaign
Agent	✅	Voice agent that will handle calls
From Phone Number	✅	Your registered phone number to call from
Concurrent Call Limit	❌	Max parallel calls (default: 5, max: 50)
Max Retry Attempts	❌	Retry failed calls (default: 3, max: 10)
Schedule Start Time	❌	When to start (leave empty for immediate)
Timezone	❌	For scheduled batches (default: UTC)

Agent Selection:

Dropdown shows all voice agents in your organization
Shows agent name and architecture
Only Pipeline/Realtime agents (text agents can’t make calls)

From Phone Number:

Must be a registered phone number in your organization
Must have outbound trunk configured
Dropdown shows all available numbers

Concurrency Settings:

Default: 5 concurrent calls
Range: 1-50
Higher = faster completion but more load
Recommended: 5-10 for most campaigns

Retry Settings:

Default: 3 attempts
Retryable statuses: no_answer, busy, timeout
Retry delays: 5 min (attempt 2), 30 min (attempt 3)

Step 4: Schedule (Optional)

Immediate Start:

Leave “Schedule Start Time” empty
Batch starts immediately after creation

Scheduled Start:

Click calendar icon
Select date from calendar
Select time (HH:MM format)
Select timezone
System converts to UTC

Calling Hours Compliance: Ensure scheduled times comply with local regulations (e.g., TCPA in US prohibits calls before 8 AM or after 9 PM local time).

Step 5: Review & Create

Review Checklist:

✅ CSV validated successfully
✅ Batch name entered
✅ Agent selected
✅ From number selected
✅ Concurrency set (default: 5)
✅ Retry attempts set (default: 3)
✅ Schedule time set (or immediate)

Click “Create & Launch Batch”:

Button shows loading spinner
Backend validates all data
Creates batch job in database
Enqueues contacts in Redis
Redirects to batch detail page

Success Response:

{
  "success": true,
  "batchJobId": "batch_xyz789",
  "totalContacts": 150,
  "estimatedDuration": "45 minutes",
  "estimatedCost": "$22.50",
  "status": "running",
  "message": "Batch campaign created successfully"
}

Batch Statuses

Status	Color	Description
Pending	Gray	Created but not started yet
Scheduled	Purple	Waiting for scheduled time
Running	Blue	Actively calling contacts
Paused	Amber	Temporarily stopped by user
Completed	Green	All contacts processed
Failed	Red	System error occurred
Cancelled	Gray	Manually cancelled by user

Viewing Batch Details

URL: /batch-calls/{batchId} Access: Click any batch in the list OR go directly via URL

Batch Detail Page Layout

Section 1: Overview Cards

4 Summary Cards:

Total Contacts
- Total number in batch
- Icon: Users
Successful Calls
- Completed successfully
- Success rate percentage
- Icon: CheckCircle
Failed Calls
- Failed after all retries
- Failure rate percentage
- Icon: XCircle
Processing
- Currently in progress
- Pending + Running
- Icon: Clock

Section 2: Batch Information

Details Card:

Field	Example
Batch ID	`batch_xyz789`
Name	January Payment Reminders
Description	Q4 payment collection campaign
Status	Running
Agent	Payment Collection Agent
From Number	+12025550100
Concurrent Limit	5
Max Attempts	3
Created	Jan 15, 2024 10:30 AM
Started	Jan 15, 2024 10:31 AM
Completed	— (ongoing)
Estimated Completion	Jan 15, 2024 11:15 AM

Section 3: Contacts List

Table Columns:

Column	Description
Contact	Name + phone number
Status	Current call status
Attempts	X / Max attempts
Last Attempt	When last called
Next Retry	When retry scheduled
Duration	Call length (if completed)
Failure Reason	Error message (if failed)

Contact Statuses:

Status	Color	Description
Pending	Gray	Not called yet
Queued	Purple	In retry queue
Dialing	Blue	Initiating call
Connected	Cyan	Call connected
Completed	Green	Successful call
Failed	Red	Final failure
Busy	Yellow	Line was busy
No Answer	Orange	No one answered
Timeout	Orange	Call timed out
Invalid Number	Red	Invalid phone format
Blocked	Red	Number blocked calls
Carrier Error	Amber	Telecom error

Pagination:

Default: 50 contacts per page
Options: 25, 50, 100
Shows: “Showing X of Y contacts”

Search:

Search by phone number
Search by name
Search by status

Filter:

Filter by status
Filter by attempt count
Filter by date range

Managing Batches

Batch Actions

Available actions depend on batch status:

Action	Pending	Scheduled	Running	Paused	Completed	Failed
View	✅	✅	✅	✅	✅	✅
Pause	❌	❌	✅	❌	❌	❌
Resume	❌	❌	❌	✅	❌	❌
Cancel	✅	✅	✅	✅	❌	❌
Delete	✅	✅	❌	✅	✅	✅
Reschedule	✅	✅	❌	❌	❌	❌
Export	❌	❌	❌	❌	✅	✅

Export Feature: Export functionality is available for Completed and Failed batches. Export options include CSV (all contacts, successful only, or failed only).

Pause a Batch

When: Temporarily stop calling (e.g., outside business hours) How:

Go to batch detail page
Click Actions (⋮) → Pause
Confirm in dialog
Status changes to “Paused”
Running calls complete normally
Pending calls wait in queue

Effect:

No new calls initiated
Contacts in queue preserved
Can resume later

Resume a Batch

When: Continue a paused batch How:

Go to batch detail page
Click Actions (⋮) → Resume
Confirm in dialog
Status changes to “Running”
Queue processing resumes

Cancel a Batch

When: Stop batch permanently How:

Go to batch detail page
Click Actions (⋮) → Cancel
Confirm in dialog (“This action cannot be undone”)
Status changes to “Cancelled”
Running calls complete
Pending calls not processed

Effect:

Irreversible action
Contacts in queue discarded
Can export results before cancelling

Delete a Batch

When: Remove batch from system How:

Go to batch list page
Click Actions (⋮) → Delete
Confirm in dialog
Batch and all contacts deleted

Permanent Deletion: This action cannot be undone. Export data first if you need to keep records.

Reschedule a Batch

When: Change scheduled start time How:

Go to batch detail page
Click Actions (⋮) → Reschedule
Opens reschedule dialog:
- Select new date
- Select new time
- Select timezone
Click Confirm
Scheduled time updated

Restrictions:

Only for Pending/Scheduled batches
Cannot reschedule running batches
New time must be in future

API Endpoint:

POST /batch/jobs/{batchId}/reschedule?scheduledStartTime={time}&timezone={tz}
Authorization: Bearer YOUR_SESSION_TOKEN

Response:

{
  "success": true,
  "message": "Batch job rescheduled successfully",
  "scheduledStartTime": "2024-01-20T14:00:00Z"
}

Export Batch

When: Download batch results for analysis or reporting How:

Go to batch detail page (Completed or Failed status)
Click Export button
Select export options:
- Format: CSV
- Filter: All / Successful / Failed
Download CSV file

Export Includes:

Contact name
Phone number
Call status
Number of attempts
Call duration
Failure reason (if failed)
Call timestamp

API Endpoint:

POST /batch/jobs/{batchId}/export
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  "format": "csv",
  "filter": "all"
}

Response: CSV file download

Export Availability: Export is only available for batches with Completed or Failed status. Running batches must complete before export.

Retry Behavior

Automatic Retry Logic

Failed calls are automatically retried:

Attempt	Timing	Retryable Statuses
Attempt 1	Immediate	—
Attempt 2	After 5 minutes	`no_answer`, `busy`, `timeout`
Attempt 3	After 30 minutes	`no_answer`, `busy`, `timeout`
After 3 failures	Marked as `permanently_failed`	—

Non-Retryable Failures

These statuses are NOT retried:

Status	Reason
`invalid_number`	Phone number format invalid
`blocked`	Number blocks calls
`carrier_error`	Telecom provider error
`agent_error`	Agent configuration error

Retry Queue

How it works:

Failed contact added to retry queue
Status changes to “Queued”
Shows “Next Retry At” time
Worker picks up at scheduled time
Attempts counter increments

View Retry Queue:

Filter contacts by status = “Queued”
Shows retry attempt number
Shows scheduled retry time

Concurrency Control

Two-Level Concurrency

TalkifAI uses sophisticated concurrency management:

Level 1: Organization Limit
         └─ Max concurrent calls across ALL batches (default: 5)

Level 2: Batch Limit
         └─ Max concurrent calls within single batch (default: 5)

Example Scenario

Setup:

Org limit: 5 concurrent calls
Batch A limit: 5 concurrent
Batch B limit: 5 concurrent

At any moment:

Max 5 calls total across both batches
NOT 10 calls (5+5)

Behavior:

If Batch A is using 3 calls
Batch B can only use 2 calls
Batch B waits if it needs more

Adjusting Concurrency

Increase for Faster Completion:

Concurrent Calls: 10-20
Best for: Large batches (1000+ contacts)
Trade-off: More load on infrastructure

Decrease for Stability:

Concurrent Calls: 3-5
Best for: Small batches (<100 contacts)
Trade-off: Slower completion

Cost Estimation

Pricing Model

Per-Call Pricing:

Base cost: $0.05/minute (infrastructure)
LLM cost: $0.015/minute (GPT-4o-mini)
STT cost: $0.003/minute (Deepgram)
TTS cost: $0.005/minute (Cartesia)

Estimated Total: ~$0.073/minute

Cost Calculator

Formula:

Total Cost = Contacts × Avg Duration × Rate

Example:
100 contacts × 3 minutes × $0.073 = $21.90

In UI:

Shows estimated cost before creation
Based on average 3-minute calls
Updates as batch progresses
Shows actual cost in analytics

Analytics & Reporting

Real-Time Metrics

Live Dashboard:

Calls completed (real-time counter)
Success rate percentage
Average call duration
Cost incurred so far
Estimated completion time

Post-Completion Reports

Summary Statistics:

Total contacts
Successful calls
Failed calls
Success rate
Average duration
Total cost
Retry statistics

Export Options:

CSV export (all contacts)
CSV export (successful only)
CSV export (failed only)
PDF report (summary)

Contact-Level Analytics

Per-Contact Data:

Call start time
Call end time
Duration
Number of attempts
Final status
Failure reason (if failed)
Recording URL (if enabled)
Transcript (if enabled)

Best Practices

Start with Test Batch

Before running 10,000 calls, test with 10-20 contacts to verify agent behavior and CSV format.

Respect Calling Hours

Schedule calls during business hours (9 AM - 6 PM local time). Use timezone-aware scheduling.

Optimize Concurrency

Start with 5 concurrent calls. Increase to 10-20 for large batches. Monitor system load.

Clean Your Data

Remove duplicates, validate phone numbers, and update invalid contacts before uploading.

Monitor Failed Calls

Check failure reasons. High invalid_number rate indicates data quality issues.

Use Descriptive Names

Name batches clearly: “2024-01-Payment-Reminders” not “Test Batch 1”.

Troubleshooting

CSV Upload Fails

Error: “CSV must have ‘phone’ column”Solution:

Check first row contains headers
Ensure one column is named phone (case-insensitive)
Verify phone numbers are in E.164 format (+1234567890)
Remove any empty rows or columns

Template:

phone,name,email
+12025550101,John Smith,john@example.com

Batch Not Starting

Status: Stuck in “Pending”Check:

Organization has available credits
From phone number has outbound trunk configured
Agent is active and uses Pipeline/Realtime architecture
Concurrency limit not exceeded by other batches

Fix: Check batch detail page for error messages

High Failure Rate

Problem: >20% calls failingCommon Causes:

Invalid phone numbers → Clean your data
Carrier blocking → Rotate phone numbers
No answers → Adjust calling hours
Agent errors → Check agent configuration

Solution: Export failed contacts, review failure reasons, fix data, create new batch

Batch Running Slowly

Problem: Taking longer than estimatedSolutions:

Increase concurrent call limit (10-20)
Check organization concurrency limit
Verify no other batches competing for capacity
Check system health (Redis, workers)

Contacts Stuck in Queue

Status: Shows “Queued” but not callingCheck:

Batch status is “Running” (not “Paused”)
Concurrency limit not maxed out
Redis worker is running
Retry time hasn’t passed yet

Fix: Refresh page, check batch status, contact support if persists

API Reference

Create Batch

POST /batch/create
Content-Type: multipart/form-data

file: [CSV file]
fromPhoneNumberId: string (required)
name: string (required)
description: string (optional)
concurrentCallLimit: number (default: 5)
maxAttempts: number (default: 3)
scheduledStartTime: ISO 8601 (optional)
timezone: string (default: UTC)

Get Batch List

GET /batch/list?page=1&pageSize=50&status=all
Authorization: Bearer YOUR_SESSION_TOKEN

Get Batch Detail

GET /batch/{batchId}
Authorization: Bearer YOUR_SESSION_TOKEN

Pause Batch

POST /batch/{batchId}/pause
Authorization: Bearer YOUR_SESSION_TOKEN

Resume Batch

POST /batch/{batchId}/resume
Authorization: Bearer YOUR_SESSION_TOKEN

Cancel Batch

POST /batch/{batchId}/cancel
Authorization: Bearer YOUR_SESSION_TOKEN

Delete Batch

DELETE /batch/{batchId}
Authorization: Bearer YOUR_SESSION_TOKEN

Reschedule Batch

POST /batch/jobs/{batchId}/reschedule?scheduledStartTime={time}&timezone={tz}
Authorization: Bearer YOUR_SESSION_TOKEN

Parameters:

scheduledStartTime — ISO 8601 datetime (e.g., 2024-01-20T14:00:00)
timezone — IANA timezone (e.g., America/New_York)

Response:

{
  "success": true,
  "message": "Batch job rescheduled successfully",
  "scheduledStartTime": "2024-01-20T14:00:00Z"
}

Export Batch

POST /batch/jobs/{batchId}/export
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  "format": "csv",
  "filter": "all"  // or "successful", "failed"
}

Response: CSV file download

Telephony — Configure phone numbers and SIP trunks
Outbound Calling — Setup guide for outbound calls
Analytics — View usage metrics and costs
Agent Configuration — Configure agents for batch calling

​Overview

​How It Works

​Navigation

​UI Overview

​Tab 1: Create New

​Tab 2: Your Batches

​Creating a Batch Campaign

​Step 1: Navigate to Batch Calls

​Step 2: Upload CSV File

​Step 3: Configure Batch Settings

​Step 4: Schedule (Optional)

​Step 5: Review & Create

​Batch Statuses

​Viewing Batch Details

​Navigation

​Batch Detail Page Layout

​Section 1: Overview Cards

​Section 2: Batch Information

​Section 3: Contacts List

​Managing Batches

​Batch Actions

​Pause a Batch

​Resume a Batch

​Cancel a Batch

​Delete a Batch

​Reschedule a Batch

​Export Batch

​Retry Behavior

​Automatic Retry Logic

​Non-Retryable Failures

​Retry Queue

​Concurrency Control

​Two-Level Concurrency

​Example Scenario

​Adjusting Concurrency

​Cost Estimation

​Pricing Model

​Cost Calculator

​Analytics & Reporting

​Real-Time Metrics

​Post-Completion Reports

​Contact-Level Analytics

​Best Practices

Start with Test Batch

Respect Calling Hours

Optimize Concurrency

Clean Your Data

Monitor Failed Calls

Use Descriptive Names

​Troubleshooting

​API Reference

​Create Batch

​Get Batch List

​Get Batch Detail

​Pause Batch

​Resume Batch

​Cancel Batch

​Delete Batch

​Reschedule Batch

​Export Batch

​Related Documentation

Overview

How It Works

Navigation

UI Overview

Tab 1: Create New

Tab 2: Your Batches

Creating a Batch Campaign

Step 1: Navigate to Batch Calls

Step 2: Upload CSV File

Step 3: Configure Batch Settings

Step 4: Schedule (Optional)

Step 5: Review & Create

Batch Statuses

Viewing Batch Details

Navigation

Batch Detail Page Layout

Section 1: Overview Cards

Section 2: Batch Information

Section 3: Contacts List

Managing Batches

Batch Actions

Pause a Batch

Resume a Batch

Cancel a Batch

Delete a Batch

Reschedule a Batch

Export Batch

Retry Behavior

Automatic Retry Logic

Non-Retryable Failures

Retry Queue

Concurrency Control

Two-Level Concurrency

Example Scenario

Adjusting Concurrency

Cost Estimation

Pricing Model

Cost Calculator

Analytics & Reporting

Real-Time Metrics

Post-Completion Reports

Contact-Level Analytics

Best Practices

Troubleshooting

API Reference

Create Batch

Get Batch List

Get Batch Detail

Pause Batch

Resume Batch

Cancel Batch

Delete Batch

Reschedule Batch

Export Batch

Related Documentation