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

# Campaigns

> Running a voice agent against a list of contacts at scale

A campaign is how you run a workflow against many contacts automatically. Instead of triggering calls one by one via the API, you upload a list of phone numbers and Asisso dials them for you — respecting scheduling windows, concurrency limits, and retry rules.

## How a campaign works

```mermaid theme={null}
flowchart LR
    CSV[Contacts CSV] --> Upload[Upload to Asisso]
    Upload --> Campaign[Create Campaign]
    Campaign --> Schedule[Scheduling & Concurrency]
    Schedule --> Calls[Outbound Calls]
    Calls --> Runs[Run Records]
    Runs --> Results[Progress & Reports]
```

1. **Upload a contacts CSV** — must have a `phone_number` column; any extra columns become `initial_context` for each call
2. **Create the campaign** — link it to a workflow, set concurrency, time slots, and retry behaviour
3. **Start it** — Asisso begins dialing contacts up to your concurrency limit
4. **Monitor progress** — track processed, completed, failed, and pending counts in real time
5. **Pause and resume** — stop and restart at any point without losing progress

## The contacts CSV

The CSV drives the campaign. Each row is one contact.

```csv theme={null}
phone_number,customer_name,account_id,plan
+14155550100,Jane Smith,acc_001,premium
+14155550101,Bob Jones,acc_002,basic
```

Columns beyond `phone_number` are automatically passed as `initial_context` to each call, making them available as template variables in your agent's prompt — so each call can feel personalised at scale.

## Scheduling and concurrency

**Concurrency** controls how many calls run simultaneously. It's capped by your telephony plan. Set it conservatively to start.

**Time slots** restrict when Asisso is allowed to dial — useful for respecting business hours or regulations:

```json theme={null}
{
  "timezone": "America/New_York",
  "time_slots": [
    { "day": "monday", "start": "09:00", "end": "17:00" },
    { "day": "tuesday", "start": "09:00", "end": "17:00" }
  ]
}
```

If no time slots are set, Asisso dials continuously once the campaign is started.

## Retry behaviour

Asisso can automatically retry contacts who didn't answer, were busy, or went to voicemail:

```json theme={null}
{
  "retry_config": {
    "max_attempts": 3,
    "retry_interval_minutes": 60
  }
}
```

## Circuit breaker

The circuit breaker automatically pauses a campaign when the call failure rate gets too high — protecting against wasted spend and telephony reputation issues caused by a misconfigured agent or a bad contact list.

When enabled, Asisso monitors the failure rate within a rolling time window. If it exceeds the threshold, the campaign is paused automatically and must be manually resumed after the issue is investigated.

| Setting               | Default | Description                                                                                                      |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| Failure Threshold (%) | `50`    | Pause when the failure rate within the window exceeds this percentage                                            |
| Window (seconds)      | `120`   | Rolling time window over which the failure rate is calculated                                                    |
| Min Calls in Window   | `5`     | Minimum number of calls required before the circuit breaker can trip — prevents false positives on small samples |

A campaign paused by the circuit breaker behaves the same as a manually paused campaign — in-flight calls complete normally, and it can be resumed once the underlying issue is resolved.

## Campaign lifecycle

| Status      | Meaning                                 |
| ----------- | --------------------------------------- |
| `draft`     | Created but not started                 |
| `running`   | Actively dialing                        |
| `paused`    | Stopped; resumes from where it left off |
| `completed` | All contacts processed                  |
| `failed`    | Encountered a fatal error               |

You can pause and resume a campaign at any time. In-flight calls complete normally before a pause takes effect.

## Results

Each contact's call creates a run record with the full transcript, recording, and gathered context — same as a manually triggered call. Use the [Get Campaign Runs](/api-reference/campaigns/runs) endpoint to retrieve them all.

See the [Campaigns API reference](/api-reference/campaigns) to get started.