Skip to main content

​
What Are Campaigns?

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

Queue Management

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

Timezone Awareness

Automatically respect local business hours. Never call contacts 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, and more in real-time.

​
How Campaigns Work

1

1. Create Campaign

Create a campaign through the TopCalls dashboard. Define the AI configuration (instructions, voice), schedule, and add your contact list. Campaign starts in draft status.
2

2. Add Contacts

Upload a CSV or add contacts through the dashboard. Each contact can have custom variables (e.g., {{name}}, {{appointment_date}}, {{order_number}}). Ensure all contacts have proper consent where required.
3

3. Start Campaign

Start the campaign via the dashboard or API (POST /v1/campaigns/{id}/start). The system picks up contacts from the queue and dispatches calls.
4

4. Execution

Calls are made respecting:
  • Account rate limits
  • 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, and more. Use GET /v1/campaigns/{id} to check progress.
6

6. Completion

Campaign automatically completes when all contacts are processed. You can also pause or stop via API.

​
Campaign Statuses

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

​
API Endpoints

Campaigns are created and configured through the TopCalls dashboard. The API provides control and monitoring:
EndpointDescription
GET /v1/campaignsList all campaigns
GET /v1/campaigns/{id}Get campaign details and stats
POST /v1/campaigns/{id}/startStart a campaign
POST /v1/campaigns/{id}/pausePause a running campaign

​
Rate Limiting & Fair Share

​
Account-Level Rate Limit

Every account has a max_calls_per_minute setting (default: 20). This controls both API calls and campaign calls.

​
Campaign Fair Share

If multiple campaigns are running, they share the account limit fairly. Campaigns that want less don’t waste capacity for others. Example:
  • Account limit: 20 calls/minute
  • 2 campaigns running
  • Each campaign gets: 10 calls/minute (fair share)

​
Timezone & Business Hours

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

​
Retry Logic

Failed calls are automatically retried:
  • Busy: Retry after a few minutes
  • No Answer: Retry after a couple of hours
  • Failed: Retry after an hour (technical issues)
  • Voicemail: Optional retry (configurable)
Maximum retry attempts are configurable per campaign.

​
Contact Variables

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

​
Campaign Analytics

Track key 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

​
Best Practices

​
Do This

  • Verify consent: Ensure all contacts have proper consent 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
  • Honor opt-outs: Immediately remove contacts who request to be removed

​
Avoid This

  • Call without consent: Never call contacts who haven’t opted in 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

​
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.