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

# Campaigns

> Outbound programs that call or message many recipients, orchestrated durably.

A **campaign** runs an agent against many recipients — outbound voice calls, WhatsApp conversations, or WhatsApp-with-voice-escalation. Campaigns are orchestrated durably so they survive restarts, respect business hours, and retry safely.

## Types

| `campaign_type`  | What it does                                                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `voice`          | Outbound phone calls to each recipient.                                                                                             |
| `whatsapp`       | WhatsApp text conversations driven by the agent.                                                                                    |
| `whatsapp_voice` | Sends a WhatsApp template, then escalates to a voice call when the recipient wants one. See the [WhatsApp guide](/guides/whatsapp). |

## Lifecycle

A campaign is a reusable **template**: you configure it as a `draft`, `publish` to lock the config, then `start` runs against the current recipient list. A finished campaign is terminal — **clone** it to run again with a fresh recipient set.

```mermaid theme={null}
stateDiagram-v2
  [*] --> draft: create (editable)
  draft --> published: publish (config locked)
  published --> scheduled: start
  scheduled --> running: bootstrap
  running --> paused: pause
  paused --> running: start (resume)
  running --> completed: finished, 0 failures
  running --> failed: finished, failures > 0
  completed --> [*]: terminal (clone to run again)
  failed --> [*]: terminal (clone to run again)
```

* Config `PATCH` is accepted while a campaign is `draft`, `scheduled`, or `paused`; `published`, `running`, and finished campaigns return `409`.
* **`start`** requires the `campaigns:write` scope (no admin role needed), at least one recipient (`400` otherwise), and the Campaign Engine to be available (`503` otherwise). It works from `draft`, `published`, `scheduled`, or `paused`. Bound agents must be **published**.
* Finished campaigns (`completed` / `failed` / `cancelled`) are **terminal and read-only** — re-running in place is disabled so a previous run's recipients and results can't be destroyed by accident.
* **`clone`** duplicates the config into a new `draft` (no recipients copied) — the supported way to run a finished campaign again. The clone records its source in `cloned_from_campaign_id`.

See the [Campaign lifecycle guide](/guides/campaign-lifecycle) for the full run mechanics.

## Recipients

Recipients are phone numbers (or WhatsApp contacts) plus their per-recipient variables, deduplicated per `(campaign, phone)`. Add them one at a time or bulk-import a CSV or `.xlsx` file.

Each recipient moves through its own states:

`pending` → `scheduled` → `calling` → `completed` / `no_answer` / `failed` / `cancelled`

## Scheduling & retries

Campaigns respect a **timezone and business hours** (default Mon–Fri, 09:00–18:00) and apply retry delays between attempts. These keys live under the campaign's `schedule`:

| Setting                       | Range / default            |
| ----------------------------- | -------------------------- |
| `max_attempts`                | 1–10                       |
| `call_timeout_seconds`        | 30–3600 (default 600)      |
| `retry_delay_minutes`         | 1–10080 (default 120)      |
| `max_recipients_per_campaign` | default 10,000, max 50,000 |

## Endpoints

| Method         | Path                                                       | Scope             |
| -------------- | ---------------------------------------------------------- | ----------------- |
| POST           | `/campaigns`                                               | `campaigns:write` |
| GET            | `/campaigns` · `/campaigns/{id}`                           | `campaigns:read`  |
| PATCH · DELETE | `/campaigns/{id}`                                          | `campaigns:write` |
| POST           | `/campaigns/{id}/recipients` · `/recipients/import`        | `campaigns:write` |
| GET            | `/campaigns/{id}/recipients` · `/attempts` · `/events`     | `campaigns:read`  |
| POST           | `/campaigns/{id}/publish` · `/start` · `/pause` · `/clone` | `campaigns:write` |

<Note>
  Campaigns require the campaign worker and Campaign Engine to be running. Without them, `start`/`pause` return `503`.
</Note>

<CardGroup cols={2}>
  <Card title="Campaign lifecycle" icon="diagram-project" href="/guides/campaign-lifecycle">How a run executes.</Card>
  <Card title="WhatsApp" icon="whatsapp" href="/guides/whatsapp">Template + voice-escalation flow.</Card>
</CardGroup>