Configuration Options
Control how your batch campaign executes with these optional settings:
{
"options": {
"priority": 5,
"maxCallsPerSecond": 10,
"scheduledStartTime": "2025-11-16T09:00:00.000Z",
"timezone": "UTC",
"retryStrategy": {
"maxAttempts": 3,
"noAnswerDelay": 3600000,
"busyDelay": 300000
},
"webhooks": {
"onBatchComplete": "https://api.your-crm.com/webhook/batch-complete",
"onCallComplete": "https://api.your-crm.com/webhook/call-complete"
},
"tags": ["Q4_campaign", "high_priority"]
}
}
Priority
Set the priority level for your batch campaign:
- Range: 1-10
- Default: 5
- Behavior: Higher priority batches are processed first
Use higher priorities (7-10) for time-sensitive campaigns like appointment reminders or urgent notifications.
Rate Limiting
Control the number of calls initiated per second:
- Field:
maxCallsPerSecond
- Range: 1-30
- Default: 10
{
"maxCallsPerSecond": 15
}
Best Practices
- Start low: Begin with 5-10 CPS and scale up
- Monitor quality: Watch for connection issues
- Check limits: Verify your telephony provider’s limits
- Consider timezone: Adjust rates for business hours
Setting too high a rate may overwhelm your telephony provider or trigger spam filters.
Scheduling
Schedule your batch to start at a specific time:
{
"scheduledStartTime": "2025-11-16T09:00:00.000Z",
"timezone": "America/New_York"
}
Fields
scheduledStartTime: ISO 8601 datetime stringtimezone: IANA timezone identifier- Requirement: Must be a future time
Common Timezones
America/New_York - Eastern TimeAmerica/Chicago - Central TimeAmerica/Los_Angeles - Pacific TimeEurope/London - UK TimeAsia/Tokyo - Japan Time
Schedule batches during business hours in your contacts’ timezone for better answer rates.
Retry Strategy
Configure how failed calls are retried:
{
"retryStrategy": {
"maxAttempts": 3,
"noAnswerDelay": 3600000,
"busyDelay": 300000
}
}
Max Attempts
- Field:
maxAttempts
- Range: 1-5
- Default: 3
Number of times to retry calling a contact.
No Answer Delay
- Field:
noAnswerDelay
- Unit: Milliseconds
- Default: 3600000 (1 hour)
Delay before retrying when call is not answered.
Busy Delay
- Field:
busyDelay
- Unit: Milliseconds
- Default: 300000 (5 minutes)
Delay before retrying when line is busy.
Recommended Settings
| Use Case | Max Attempts | No Answer Delay | Busy Delay |
|---|
| Urgent notifications | 2 | 30 min | 5 min |
| Standard outreach | 3 | 1 hour | 15 min |
| Low-priority campaigns | 2 | 4 hours | 30 min |
Webhooks
Receive HTTP notifications for batch events:
{
"webhooks": {
"onBatchComplete": "https://api.your-crm.com/webhook/batch-complete",
"onCallComplete": "https://api.your-crm.com/webhook/call-complete",
"onBatchFailed": "https://api.your-crm.com/webhook/batch-failed"
}
}
Available Webhooks
onBatchComplete
Triggered when all calls in the batch are finished.
{
"event": "batch.completed",
"batchId": "batch_123",
"statistics": {
"total": 1000,
"succeeded": 850,
"failed": 150
}
}
onCallComplete
Triggered after each individual call completes.
{
"event": "call.completed",
"callId": "call_456",
"status": "COMPLETED",
"duration": 180,
"summary": "Call summary text..."
}
onBatchFailed
Triggered if the batch fails to process.
{
"event": "batch.failed",
"batchId": "batch_123",
"error": "Insufficient credits"
}
Add tags to organize and filter batches:
{
"tags": ["Q4_campaign", "high_priority", "lead_qualification"]
}
Use Cases
- Campaign tracking: Group related batches
- Filtering: Find batches by category
- Reporting: Analyze performance by tag
- Organization: Manage multiple campaigns
Complete Example
{
"agentId": "agent_123",
"userId": "user_456",
"contacts": [...],
"options": {
"priority": 7,
"maxCallsPerSecond": 12,
"scheduledStartTime": "2025-11-16T09:00:00.000Z",
"timezone": "America/New_York",
"retryStrategy": {
"maxAttempts": 3,
"noAnswerDelay": 3600000,
"busyDelay": 300000
},
"webhooks": {
"onBatchComplete": "https://api.yourcompany.com/webhooks/batch-complete",
"onCallComplete": "https://api.yourcompany.com/webhooks/call-complete"
},
"tags": ["Q4_2025", "lead_qualification", "high_value"]
}
}
Next Steps
