Skip to main content

​
What Are Campaigns?

Campaigns are production-ready queue management systems for automated outbound calls. They automatically process contact lists, handle retries, respect timezones, and provide real-time monitoring. Replace manual dialing and scale without hiring. Use cases include appointment reminders, post-purchase follow-ups, renewal reminders, and lead qualification for consented contacts.

Queue Management

Process thousands of leads efficiently with intelligent queue management and fair-share rate limiting.

Timezone Awareness

Automatically respect local business hours. Never call leads outside their timezone’s acceptable hours.

Smart Retries

Automatically retry busy signals, no-answers, and failed calls with configurable retry logic.

Real-Time Analytics

Monitor connection rates, completion rates, conversions, and more in real-time.

​
How Campaigns Work

1

1. Create Campaign

Define the AI configuration (instructions, voice, model), schedule, and target leads. Campaign starts in draft status.
2

2. Add Contacts

Upload a CSV or add contacts via API. Each contact can have custom variables (e.g., {{name}}, {{appointment_date}}, {{order_number}}). Ensure all contacts have proper consent or existing business relationship where required.
3

3. Start Campaign

Change status to running. The Campaign Producer picks up leads from the queue and dispatches them to the Dispatcher.
4

4. Execution

Calls are made respecting:
  • Account rate limits (max_calls_per_minute)
  • Campaign parallel call limits
  • Timezone restrictions (business hours)
  • Retry logic
  • Compliance requirements (opt-out handling, frequency limits)
5

5. Monitoring

Track real-time stats: calls completed, connection rates, conversions, and more.
6

6. Completion

Campaign automatically completes when all leads are processed. You can also pause or stop manually.

​
Campaign Statuses

StatusDescriptionActions Available
draftConfiguration phase, no calls madeEdit, Start
scheduledWaiting for start timeEdit, Start, Cancel
runningActively dispatching callsPause, Stop
pausedTemporarily stoppedResume, Stop
completedAll leads processedView stats, Archive
cancelledPermanently stoppedView stats, Archive

​
Rate Limiting & Fair Share

​
Account-Level Rate Limit

Every account has a max_calls_per_minute setting (default: 20). This single limit controls:
  • API calls: POST /v1/calls requests
  • Campaign calls: All campaigns share this limit fairly

​
Campaign Fair Share

If multiple campaigns are running, they share the account limit fairly: 
desired = MIN(run.calls_per_minute, campaign.max_parallel_calls)
scale_factor = total_demand <= account_limit ? 1 : account_limit / total_demand
effective_rate = ROUND(desired * scale_factor)
This smart allocation ensures full utilization - campaigns that want less don’t waste capacity. Example:
  • Account limit: 20 calls/minute
  • 2 campaigns running
  • Each campaign gets: 20 / 2 = 10 calls/minute (fair share)

​
Campaign Parallel Limits

Each campaign can set max_parallel_calls (default: 10) to control its own throughput: 
{
  "name": "Sales Outreach Q1",
  "max_parallel_calls": 5,  // This campaign uses max 5 calls/minute
  "instructions": "..."
}

​
Timezone & Business Hours

Never call contacts outside their local business hours. This helps maintain compliance and improves connection rates: 
{
  "timezone": "America/New_York",
  "dispatch_hours": {
    "start": "09:00",
    "end": "17:00"
  }
}
Timezone awareness helps prevent compliance issues and improves connection rates. Contacts are only called during their local business hours. Customers are responsible for ensuring compliance with local calling laws (TCPA/TSR/DNC, GDPR).

​
Retry Logic

Automatically retry failed calls: 
{
  "max_attempts_per_lead": 3,
  "retry_delays": {
    "busy": "5 minutes",
    "no_answer": "2 hours",
    "failed": "1 hour"
  }
}
Retry Scenarios:
  • Busy: Retry after 5 minutes
  • No Answer: Retry after 2 hours (different time of day)
  • Failed: Retry after 1 hour (technical issues)
  • Voicemail: Optional retry (configurable)

​
Contact Variables

Personalize each call with contact-specific data: 
{
  "leads": [
    {
      "phone_number": "+14155551234",
      "name": "John Smith",
      "appointment_date": "2025-12-24",
      "appointment_time": "3:00 PM",
      "order_number": "ORD-12345"
    }
  ]
}
Use in instructions: 
You are calling {{name}} about their appointment on {{appointment_date}} 
at {{appointment_time}}.

​
Campaign Analytics

Track key operational metrics in real-time:
MetricDescription
Total ContactsNumber of contacts in campaign
Calls CompletedSuccessfully finished calls
Calls PendingStill in queue
Calls FailedTechnical failures
Connection Rate% of calls that connected
Completion Rate% that completed successfully
Avg DurationAverage call length

​
Webhooks

Subscribe to campaign-level events:
  • campaign.started: Campaign began running
  • campaign.paused: Campaign was paused
  • campaign.resumed: Campaign resumed
  • campaign.completed: All leads processed
  • campaign.stopped: Campaign was cancelled
Plus call-level events:
  • call.completed: Individual call finished
  • call.failed: Individual call failed

​
Best Practices

​
✅ Do This

  • Verify consent: Ensure all contacts have proper consent or existing business relationship where required
  • Start small: Test with 10-20 contacts before scaling
  • Monitor closely: Watch connection rates and adjust
  • Respect timezones: Always configure timezone and business hours
  • Set retry limits: Don’t retry indefinitely
  • Use variables: Personalize calls with contact data
  • Track outcomes: Define clear success criteria
  • Honor opt-outs: Immediately remove contacts who request to be removed

​
❌ Don’t Do This

  • Call without consent: Never call contacts who haven’t opted in or don’t have an existing business relationship where required
  • Ignore rate limits: Respect account and campaign limits
  • Call outside hours: Always use timezone awareness
  • Skip testing: Test your instructions on a few calls first
  • Over-retry: Set reasonable max attempts
  • Forget monitoring: Watch metrics and adjust
  • Ignore opt-outs: Always honor do-not-call requests immediately

​
Example: Lead Qualification Campaign

Compliance: This example is for consented contacts only. Ensure all contacts have opted in or have an existing business relationship. Always honor opt-out requests immediately.
{
  "name": "Q1 Lead Qualification",
  "instructions": "You are Alex, a sales rep for TopCalls. Your goal is to qualify {{name}} as a potential customer and book a demo if interested. If they request to be removed from the call list, immediately honor that request.",
  "first_sentence": "Hi {{name}}, this is Alex from TopCalls. I'm reaching out because your company {{company_name}} might benefit from our AI voice platform.",
  "voice": "alloy",
  "mode": "realtime",
  "timezone": "America/New_York",
  "dispatch_hours": {
    "start": "09:00",
    "end": "17:00"
  },
  "max_parallel_calls": 10,
  "max_attempts_per_lead": 3,
  "webhook_url": "https://your-app.com/webhooks/campaign"
}

​
Next Steps

Making Calls Guide

Learn how to make individual calls via API.

Webhooks Guide

Set up webhooks to receive real-time campaign and call events.