Run your first campaign

Create a voice campaign, add recipients, publish, start, and monitor it.

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

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

2. 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": "[phone]", "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.

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

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

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