Running Bulk CampaignsCopy Anchor Link

Talkar's campaign engine turns a CSV lead list into structured outbound calls while respecting calling hours, caller-ID rotation, organization concurrency caps, and automatic failure protection. Campaigns always execute the workflow's Published snapshot.

Step 1: Prepare & Upload Your CSVCopy Anchor Link

Upload your .csv file (under 10 MB) via POST /api/v1/s3/presigned-upload-url, then create the campaign via POST /api/v1/campaign/create (passing required source_type: "csv"):

1. Strict phone_number Formatting (+ Required): Every non-empty phone_number value must start with + (E.164 format, e.g., +919876543210). Campaign creation fails immediately and reports the exact invalid row numbers if any row omits +.
2. UTF-8, Headers & Row Count: Files must be valid UTF-8 with at least 1 data row. Column headers are automatically trimmed and lowercased on ingest.
3. Duplicate Lead Rejection: Duplicate phone_number entries within the same CSV (compared after stripping spaces, -, (, ), and .) are rejected at creation time.
4. Required Template Variable Validation: Every bare workflow prompt variable ({{customer_name}}) without a nested prefix (initial_context.*, gathered_context.*) or default/fallback filter (| default, | fallback:value)—excluding system variables provider, campaign_id, and source_uuid—must exist as a CSV column header and be non-empty in every single row. (Add | default if using {{current_time_*}} or {{current_weekday_*}} inside workflows destined for campaigns.)
5. Optional Caller-ID Override (caller_number): Include caller_number per row to prefer a verified DID from the trunk pool. If that CLI stays busy past 20s, the dispatcher automatically falls back to another active CLI in the pool.

3-Step API CSV Upload & Create FlowCopy Anchor Link

When automating campaigns from your CRM or n8n.talkar.in:

1. Request a 15-minute presigned S3 upload URL (POST /api/v1/s3/presigned-upload-url):

{
  "file_name": "leads_nov.csv",
  "file_size": 24576,
  "content_type": "text/csv"
}

Returns {"upload_url": "https://...", "file_key": "campaigns/42/<uuid>_leads_nov.csv", "expires_in": 900}. 2. Upload raw CSV bytes directly to upload_url via HTTP PUT:

curl -X PUT "<upload_url>" \
  -H "Content-Type: text/csv" \
  --data-binary @leads_nov.csv

3. Create the campaign (POST /api/v1/campaign/create) passing file_key as source_id:

{
  "name": "November Sales Outreach",
  "workflow_id": 128,
  "source_type": "csv",
  "source_id": "campaigns/42/<uuid>_leads_nov.csv",
  "telephony_configuration_id": 7,
  "max_concurrency": 5,
  "retry_config": {
    "enabled": true,
    "max_retries": 2,
    "retry_delay_seconds": 120,
    "retry_on_busy": true,
    "retry_on_no_answer": true,
    "retry_on_voicemail": true
  },
  "schedule_config": {
    "enabled": true,
    "timezone": "Asia/Kolkata",
    "slots": [
      { "day_of_week": 0, "start_time": "10:00", "end_time": "19:00" },
      { "day_of_week": 1, "start_time": "10:00", "end_time": "19:00" }
    ]
  },
  "circuit_breaker": {
    "enabled": true,
    "failure_threshold": 0.5,
    "window_seconds": 120,
    "min_calls_in_window": 5
  }
}

Step 2: Trunks, Rate Limits, Concurrency & ProgressCopy Anchor Link

Leads vs. Call Attempts & Completion ProgressCopy Anchor Link

• Leads vs. Attempts: One CSV lead row can trigger multiple call attempts (1 + max_retries) when busy/no-answer/voicemail retries run. Use GET /api/v1/campaign/{id}/runs with latest_per_lead and sort_by to view either per-lead outcomes or every attempt.
• Completion Clamp: Live progress bars clamp at 99.9% while the final calls finish, with a 30s inactivity grace period before marking a campaign completed.

Step 3: Retries, Calling Schedules & Circuit BreakerCopy Anchor Link

Automatic Retries (retry_config)Copy Anchor Link

Configure how unsuccessful connection attempts reschedule with randomized ±20% jitter (0.8x–1.2x) to avoid synchronized retry storms:

• enabled: true / false
• max_retries (0–10): Maximum retry attempts per lead (total attempts = max_retries + 1).
• retry_delay_seconds (30–3600): Base wait window (default 120s).
• Trigger toggles: retry_on_busy, retry_on_no_answer, and retry_on_voicemail. Initiation failures also retry while retry_count < max_retries.

Calling Hours & Business Schedules (schedule_config)Copy Anchor Link

{
  "enabled": true,
  "timezone": "Asia/Kolkata",
  "slots": [
    { "day_of_week": 0, "start_time": "10:00", "end_time": "19:00" },
    { "day_of_week": 1, "start_time": "10:00", "end_time": "19:00" },
    { "day_of_week": 2, "start_time": "10:00", "end_time": "19:00" },
    { "day_of_week": 3, "start_time": "10:00", "end_time": "19:00" },
    { "day_of_week": 4, "start_time": "10:00", "end_time": "19:00" }
  ]
}

• day_of_week: 0 = Monday through 6 = Sunday (1 to 50 slots).
• timezone: Valid IANA timezone (e.g. "Asia/Kolkata", "America/New_York", "UTC").
• Window validation: start_time and end_time cannot be identical (start_time != end_time). Overnight slots (start_time > end_time, e.g. 22:00 to 02:00) are supported automatically.
• Outside window behavior: Campaign remains running cleanly until the next open slot—it does not fail or pause.

Sliding-Window Circuit Breaker (circuit_breaker)Copy Anchor Link

• Fields & Bounds:
  • enabled (default true)
  • failure_threshold (0.0 – 1.0, default 0.5 = 50%)
  • window_seconds (30 – 600, default 120)
  • min_calls_in_window (1 – 100, default 5)
• What trips it: Only telephony/carrier failures (failed, error, or initiation failures). Normal unanswered outcomes (busy, no-answer) do not trip it.
• Recovery: Trips move the campaign to paused (paused_reason = "circuit_breaker"). Resuming clears the rolling window cleanly.

Step 4: Campaign Lifecycle APIs, Auto-Pauses & CSV ReportsCopy Anchor Link

Lifecycle Endpoints & ControlsCopy Anchor Link

Auto-Pause & Halt ConditionsCopy Anchor Link

Campaign Export ReportsCopy Anchor Link

Download campaign CSV reports with optional start_date and end_date filters. Exports automatically flatten per-lead extracted_variables alongside canonical outcomes and core audit columns (Campaign ID, Agent ID, Agent Definition ID, Created At, phone numbers, duration, disposition, and tags).