Campaign Management

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

Track real-time stats: calls completed, connection rates, and more. Use GET /v1/campaigns/{id} to check progress.

6. Completion

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

Campaign Statuses

Status	Description	Actions Available
`draft`	Configuration phase, no calls made	Edit, Start
`scheduled`	Waiting for start time	Edit, Start, Cancel
`running`	Actively dispatching calls	Pause, Stop
`paused`	Temporarily stopped	Resume, Stop
`completed`	All contacts processed	View stats
`failed`	Stopped by an unrecoverable error	View stats
`cancelled`	Permanently stopped	View stats

API Endpoints

Campaigns are created and configured through the TopCalls dashboard. The API provides control and monitoring:

Endpoint	Description
`GET /v1/campaigns`	List all campaigns
`GET /v1/campaigns/{id}`	Get campaign details and stats
`POST /v1/campaigns/{id}/start`	Start a campaign
`POST /v1/campaigns/{id}/pause`	Pause a running campaign
`POST /v1/campaigns/{id}/resume`	Resume a paused campaign
`POST /v1/campaigns/{id}/stop`	Permanently stop a campaign
`POST /v1/campaigns/{id}/test`	Place a real, billed test call using the campaign’s configuration

Account-Level Rate Limit

Every account has a max_calls_per_minute setting (default: 20). This controls both API calls and campaign calls. 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

Each campaign has a retry schedule that decides when a lead is called again after an unsuccessful attempt. The schedule is a list of slots, one per retry, and each slot is one of:

A relative delay: “wait 30 minutes”, counted from the previous attempt
A fixed time: “at 6:00 PM”, on the lead’s local clock

Retries follow the slots in order until the lead answers or the campaign’s maximum attempts per lead is reached. If a fixed-time slot is already in the past when the retry comes due, it is skipped and the next slot applies. Whether a given outcome retries at all depends on its disposition; a caller who asked not to be called again is not retried. Configure the schedule and the attempt cap in the campaign editor. Presets (Gentle, Standard, Aggressive) cover common cases, and every slot stays editable.

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

Bot Protection

Campaign calls include bot protection by default. When the person on the line behaves like an automated system rather than a human (scripted lines, the same non-answer to different questions), the call ends automatically so it doesn’t burn minutes. Turn it off per campaign in the editor, or per call with bot_protection_enabled: false.

Voicemail Detection

Campaign calls hang up automatically when they reach an answering machine or voicemail in any language, so a mailbox greeting doesn’t run up minutes. The assistant may also end the call on its own if it recognizes an automated system.

Campaign Analytics

Track key metrics in real-time:

Metric	Description
Total Contacts	Number of contacts in campaign
Calls Completed	Successfully finished calls
Calls Pending	Still in queue
Calls Failed	Technical failures
Connection Rate	% of calls that connected
Completion Rate	% that completed successfully
Avg Duration	Average 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

Getting Started

Core Concepts

Guides

Use Cases

Integrations

What Are Campaigns?

Queue Management

Timezone Awareness

Smart Retries

Real-Time Analytics

How Campaigns Work

Campaign Statuses

API Endpoints

Account-Level Rate Limit

Timezone & Business Hours

Retry Logic

Contact Variables

Bot Protection

Voicemail Detection

Campaign Analytics

Best Practices

Do This

Avoid This

Next Steps

Making Calls Guide

Webhooks Guide

​What Are Campaigns?

Queue Management

Timezone Awareness

Smart Retries

Real-Time Analytics

​How Campaigns Work

​Campaign Statuses

​API Endpoints

​Rate Limiting & Fair Share

​Account-Level Rate Limit

​Campaign Fair Share

​Timezone & Business Hours

​Retry Logic

​Contact Variables

​Bot Protection

​Voicemail Detection

​Campaign Analytics

​Best Practices

​Do This

​Avoid This

​Next Steps

Making Calls Guide

Webhooks Guide

What Are Campaigns?

How Campaigns Work

Campaign Statuses

API Endpoints

Rate Limiting & Fair Share

Account-Level Rate Limit

Campaign Fair Share

Timezone & Business Hours

Retry Logic

Contact Variables

Bot Protection

Voicemail Detection

Campaign Analytics

Best Practices

Do This

Avoid This

Next Steps