> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign Management

> Queue management for automated outbound calls. Handle thousands of contacts with timezone awareness, retry logic, and real-time monitoring.

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

<CardGroup cols={2}>
  <Card title="Queue Management" icon="list-check">
    Process thousands of contacts efficiently with intelligent queue management and fair-share rate limiting.
  </Card>

  <Card title="Timezone Awareness" icon="clock">
    Automatically respect local business hours. Never call contacts outside their timezone's acceptable hours.
  </Card>

  <Card title="Smart Retries" icon="arrow-rotate-right">
    Automatically retry busy signals, no-answers, and failed calls with configurable retry logic.
  </Card>

  <Card title="Real-Time Analytics" icon="chart-line">
    Monitor connection rates, completion rates, and more in real-time.
  </Card>
</CardGroup>

## How Campaigns Work

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="5. Monitoring">
    Track real-time stats: calls completed, connection rates, and more. Use `GET /v1/campaigns/{id}` to check progress.
  </Step>

  <Step title="6. Completion">
    Campaign automatically completes when all contacts are processed. You can also pause or stop via API.
  </Step>
</Steps>

## 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 |

## 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:

```json theme={null}
{
  "timezone": "America/New_York",
  "dispatch_hours": {
    "start": "09:00",
    "end": "17:00"
  }
}
```

<Note>
  Timezone awareness helps prevent compliance issues and improves connection rates. Customers are responsible for compliance with local calling laws (TCPA/TSR/DNC, GDPR).
</Note>

## 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:

```json theme={null}
{
  "phone_number": "+14155551234",
  "name": "John Smith",
  "appointment_date": "2025-12-24",
  "appointment_time": "3:00 PM"
}
```

Use in instructions:

```text theme={null}
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`.

## 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

## Next Steps

<CardGroup cols={2}>
  <Card title="Making Calls Guide" icon="phone" href="/guides/making-calls">
    Learn how to make individual calls via API.
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Set up webhooks to receive real-time campaign and call events.
  </Card>
</CardGroup>