> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ailunapro.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 Voice AiLunaPro 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 AiLunaPro]
    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** — AiLunaPro 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,greeting_override_type,greeting_override_text
+14155550100,Jane Smith,acc_001,premium,text,Hello {{customer_name}}
+14155550101,Bob Jones,acc_002,basic,text,Welcome back {{customer_name}}
```

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.

To override the Start node greeting for a row, set `greeting_override_type` to `text` and provide `greeting_override_text`. The text can use other columns as template variables. For a recorded greeting, set the type to `audio` and provide its public ID in `greeting_override_recording_id`. Leave the override columns empty to use the greeting configured in the Start node.

## 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 AiLunaPro 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, AiLunaPro dials continuously once the campaign is started.

## Retry behaviour

AiLunaPro 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 too many connected calls end with an AI pipeline failure, such as an STT, LLM, or TTS error.

While the campaign is running, each finished pipeline with a known outcome contributes one sample, including calls made through ARI. The failure rate is failed pipelines divided by all counted pipelines in the rolling time window. Unclassified framework cancellations, busy, no-answer, carrier rejections, and failed dial attempts are excluded. Calls finishing while the campaign is paused do not enter the window. A telephony provider's "completed" callback does not count as a successful pipeline.

When enabled, the circuit breaker pauses the campaign once the minimum sample size is reached and the failure rate meets or exceeds the threshold. You must manually resume the campaign after investigating the issue.

| Setting | Default | Description |
| - | - | - |
| Failure Threshold (%) | `50` | Pause when the pipeline failure rate within the window meets or exceeds this percentage |
| Window (seconds) | `120` | Rolling time window over which the failure rate is calculated |
| Min Calls in Window | `5` | Minimum number of finished pipelines 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.

### Provider errors

An HTTP 401, 402, or 403 reported by a campaign call's STT, TTS, LLM, realtime, or outbound telephony provider immediately pauses that campaign. This applies independently of the failure-rate threshold and sample size, including errors handled by an LLM fallback. The campaign log records the provider, status code, and workflow run that caused the pause.

Fix the provider issue, then resume the campaign normally. Resuming clears the pause; another 401, 402, or 403 pauses it again. Other provider errors do not trigger this immediate pause; pipeline failures still contribute to the existing failure-rate breaker.

Calls waiting to dial recheck the campaign state after each rate-limit wait, immediately before trying rate admission. If paused, their contacts remain queued and their reserved call capacity is released. Calls already dialed can finish. This protection does not block API-triggered calls or other campaigns using the same provider.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.