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

# Campaigns

> Running a workflow 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 SentiVue Talk 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 SentiVue Talk]
    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** — SentiVue Talk 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 context to each call, making them available as template variables in your agent's prompt — so each call can feel personalised at scale.

### Start from the generated template

When you create a campaign, SentiVue Talk offers a **downloadable CSV template** built from the workflow you selected. The header row contains `phone_number` plus every template variable your workflow actually uses, and a few example rows show what valid data looks like. Replace the examples with your contacts and upload.

Using the template is the easiest way to avoid the most common upload failure: a workflow variable with no matching column.

<Note>
  Phone numbers in the template are written as `="+14155550100"` so Excel and Google Sheets keep the leading `+` instead of treating the value as a number and stripping it. SentiVue Talk removes this wrapper on upload, so the file works whether or not your spreadsheet app rewrites it.
</Note>

### What gets checked before the campaign starts

Your file is validated as soon as you upload it, so problems surface immediately rather than mid-campaign. Errors tell you the exact row numbers to fix.

* **A `phone_number` column is required.** Column names are case-insensitive.
* **Every number must start with `+`** and include the country code.
* **Numbers must be unique** within a campaign. Duplicates are rejected.
* **Every template variable your workflow uses must exist as a column** and have a value in every row.

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

## Retry behaviour

SentiVue Talk 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, SentiVue Talk 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](/talk/api-reference/campaigns/runs) endpoint to retrieve them all.

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