Campaigns

Campaigns let you call hundreds or thousands of contacts automatically with your AI agent. Features include concurrency control, automatic retries, blackout windows, and real-time status tracking.

Creating a Campaign

$
curl -X POST https://api.levrage.ai/v1/campaigns \
>
  -H "Authorization: Bearer $API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "January Sales Outreach",
>
    "agent_id": "YOUR_AGENT_ID",
>
    "phone_number": "+919240018601",
>
    "phone_column": "phone",
>
    "contacts": [
>
      {"phone": "+919876543210", "name": "Alice", "company": "TechCo"},
>
      {"phone": "+919876543211", "name": "Bob", "company": "FinCo"},
>
      {"phone": "+919876543212", "name": "Charlie", "company": "RetailCo"}
>
    ],
>
    "max_concurrent_calls": 3
>
  }'

Required Fields

Contacts Format

Each contact is a JSON object. The only required field is the phone number (matching phone_column). Any additional fields are passed to the agent as metadata:

1
{
2
  "contacts": [
3
    {
4
      "phone": "+919876543210",
5
      "name": "Alice",
6
      "email": "alice@example.com",
7
      "loan_amount": "500000",
8
      "status": "warm_lead"
9
    }
10
  ]
11
}

Concurrency Control

Control how many calls run in parallel:

1
{
2
  "max_concurrent_calls": 5
3
}

Automatic Retries

Retry contacts who didn’t answer, went to voicemail, or had failed calls:

1
{
2
  "retry_config": {
3
    "enabled": true,
4
    "on_statuses": ["no_answer", "voicemail", "failed"],
5
    "interval_value": 30,
6
    "interval_unit": "minutes",
7
    "max_retries": 3,
8
    "respect_calling_hours": true
9
  }
10
}

Scheduling & Blackout Windows

Calling Hours

Restrict calls to business hours:

1
{
2
  "daily_start_time": "09:00",
3
  "daily_end_time": "21:00",
4
  "timezone": "Asia/Kolkata"
5
}

Blackout Periods

Define no-call windows (e.g., lunch break, holidays):

1
{
2
  "blackout_periods": [
3
    {"start": "13:00", "end": "14:00"},
4
    {"start": "22:00", "end": "08:00"}
5
  ]
6
}

Schedule for Later

1
{
2
  "schedule_time": "2025-02-01T09:00:00+05:30",
3
  "timezone": "Asia/Kolkata"
4
}

Campaign Lifecycle

Created → In Progress → Completed
              ↓    ↑
           Paused   Resume
              ↓
           Stopped

Pause a Campaign

$
curl -X POST -H "Authorization: Bearer $API_KEY" \
>
     "https://api.levrage.ai/v1/campaigns/{campaign_id}/pause"

Resume a Campaign

$
curl -X POST -H "Authorization: Bearer $API_KEY" \
>
     "https://api.levrage.ai/v1/campaigns/{campaign_id}/resume"

Stop a Campaign

Permanently stops the campaign. Cannot be resumed.

$
curl -X POST -H "Authorization: Bearer $API_KEY" \
>
     "https://api.levrage.ai/v1/campaigns/{campaign_id}/stop"

Cancel a Scheduled Campaign

Cancel a campaign that hasn’t started yet:

$
curl -X POST -H "Authorization: Bearer $API_KEY" \
>
     "https://api.levrage.ai/v1/campaigns/{campaign_id}/cancel"

Monitoring Campaigns

List Campaigns

$
curl -H "Authorization: Bearer $API_KEY" \
>
     "https://api.levrage.ai/v1/campaigns?page=1&page_size=20"

Get Campaign Details

$
curl -H "Authorization: Bearer $API_KEY" \
>
     "https://api.levrage.ai/v1/campaigns/{campaign_id}"

Response includes real-time progress:

1
{
2
  "success": true,
3
  "data": {
4
    "id": "campaign_uuid",
5
    "name": "January Sales Outreach",
6
    "status": "in_progress",
7
    "total_contacts": 500,
8
    "valid_contacts": 485,
9
    "completed": 120,
10
    "failed": 5,
11
    "no_answer": 30,
12
    "voicemail": 8,
13
    "pickup_rate": 73.5,
14
    "pending_retries": 25,
15
    "max_concurrent_calls": 5
16
  }
17
}

Best Practices

1. Start small — Test with 5-10 contacts before scaling
2. Set calling hours — Respect your contacts’ time zones
3. Use retries wisely — 2-3 retries with 30-minute intervals works well
4. Pass metadata — Personalized calls have 2x higher conversion
5. Monitor pickup rates — If below 30%, check your source number reputation
6. Use blackout periods — Avoid calling during lunch and late night