mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-07 07:55:16 +02:00
100 lines
4 KiB
Text
100 lines
4 KiB
Text
---
|
|
title: "Campaigns"
|
|
sidebarTitle: "Campaigns (Bulk Outbound Calls)"
|
|
description: "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 Dograh dials them for you — respecting scheduling windows, concurrency limits, and retry rules.
|
|
|
|
## How a campaign works
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
CSV[Contacts CSV] --> Upload[Upload to Dograh]
|
|
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** — Dograh 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
|
|
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 Dograh is allowed to dial — useful for respecting business hours or regulations:
|
|
|
|
```json
|
|
{
|
|
"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, Dograh dials continuously once the campaign is started.
|
|
|
|
## Retry behaviour
|
|
|
|
Dograh can automatically retry contacts who didn't answer, were busy, or went to voicemail:
|
|
|
|
```json
|
|
{
|
|
"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, Dograh 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.
|