Run your first campaign

This walkthrough runs an outbound voice campaign end to end. For the execution mechanics behind it, see the Campaign lifecycle deep-dive; for the states, the Campaigns concept.

Prerequisites

A published agent — campaigns bind only published agents. See Create & publish an agent.
The campaign worker and Campaign Engine running (otherwise start returns 503).

Campaign management uses the campaigns:write / campaigns:read scopes — a workspace API key that carries them can run the whole flow (no admin role required).

Create the campaign

curl -X POST "$LEHAR_BASE_URL/campaigns" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March renewals",
    "campaign_type": "voice",
    "voice_agent_id": "agent_sales_hi",
    "timezone": "Asia/Kolkata",
    "schedule": {
      "business_hours": [ { "start": "09:00", "end": "18:00", "days": ["mon","tue","wed","thu","fri"] } ],
      "max_attempts": 3,
      "retry_delay_minutes": 120
    }
  }'

The campaign starts as a draft.

Agents are bound per channel: use voice_agent_id for voice, whatsapp_agent_id for whatsapp, and both for whatsapp_voice. The bound agent must be published and match the channel.

Add recipients

Add them one at a time, with per-recipient variables:

curl -X POST "$LEHAR_BASE_URL/campaigns/$CAMPAIGN_ID/recipients" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+919876543210", "variables": { "callee_name": "Jane", "company": "Acme" } }'

Or bulk-upload a CSV or .xlsx file (multipart) to POST /campaigns/{id}/recipients/import. Recipients are deduplicated per (campaign, phone); up to 50,000 per campaign.

Publish

Lock the configuration so the run is reproducible:

curl -X POST "$LEHAR_BASE_URL/campaigns/$CAMPAIGN_ID/publish" -H "X-API-KEY: $LEHAR_API_KEY"

After publishing, config PATCH is rejected (409) — a published campaign is a reusable template.

Start

curl -X POST "$LEHAR_BASE_URL/campaigns/$CAMPAIGN_ID/start" -H "X-API-KEY: $LEHAR_API_KEY"

The status moves scheduled → running. Calls are placed within the campaign’s business hours, retrying per the schedule.

start needs at least one recipient (else 400) and the Campaign Engine available (else 503). Any caller with campaigns:write can start a run — no admin role required.

Monitor

Track progress and per-recipient outcomes:

curl "$LEHAR_BASE_URL/campaigns/$CAMPAIGN_ID"          -H "X-API-KEY: $LEHAR_API_KEY"   # status
curl "$LEHAR_BASE_URL/campaigns/$CAMPAIGN_ID/attempts" -H "X-API-KEY: $LEHAR_API_KEY"   # per attempt
curl "$LEHAR_BASE_URL/campaigns/$CAMPAIGN_ID/events"   -H "X-API-KEY: $LEHAR_API_KEY"   # audit log

List responses are paged: pass ?limit= (default 20, max 100) and ?offset=. Attempts and recipients report pagination.total; the event log pages without one.Recipients end as completed, no_answer, or failed; the campaign completes completed (zero failures) or failed.

Pause, resume, and re-run

Pause / resume — POST /campaigns/{id}/pause halts new attempts; POST /campaigns/{id}/start resumes.
Re-run — a finished campaign is terminal and read-only. To run it again, clone it (POST /campaigns/{id}/clone): the clone copies the config into a fresh draft with no recipients (its source recorded in cloned_from_campaign_id). Publish the clone, add a new recipient list, then start.

Campaign lifecycle

How a run executes under the hood.

WhatsApp campaigns

Template + voice-escalation flow.

Get Started

Key Concepts

Guides

Deep Dives

Run your first campaign

Prerequisites

Pause, resume, and re-run

Campaign lifecycle

WhatsApp campaigns

​Prerequisites

​Pause, resume, and re-run

Campaign lifecycle

WhatsApp campaigns

Prerequisites

Pause, resume, and re-run