Skip to main content

​
Batch Calls & Campaigns Overview

Batch calls (campaigns) let you run high-volume outbound calling while keeping control over:
  • Who to call (contacts and folders)
  • Which agent to use
  • When to call (time windows, timezones, daily caps)
  • How to monitor and optimize results
This page gives you the conceptual model before you dive into detailed scheduling and API guides.

​
Who this is for

  • Teams running outbound sales, renewals, collections, or large notification campaigns.
  • Developers wiring the batch calling API and webhooks into internal tools.

​
Key objects in a campaign

Every campaign ties together:
  • Agent – The voice and behavior for all calls in the campaign.
  • Outbound numbers – One or more telephony numbers to place calls from.
  • Contact source – How you pick who to call:
    • A contact folder (recommended).
    • Explicit contact_ids.
    • Inline contacts provided in the create request.
  • Schedule – When to run:
    • schedule_type, scheduled_at, timezone.
    • Daily window: start_time, end_time, working_days.
    • Volume: max_calls_per_day, max_concurrent_calls.
From these, Truedy generates campaign contacts and orchestrates individual calls.

​
Lifecycle and statuses

Campaigns move through a clear lifecycle:
  • draft – Created, contacts attached, settings editable. Nothing is scheduled yet.
  • scheduled – Contacts have scheduled_at timestamps and are waiting to fire.
  • active – Calls are currently being placed by the scheduler.
  • paused – Scheduler is halted; future calls are held until you resume.
  • completed – All contacts have reached a terminal status.
  • failed – A configuration or scheduling error prevented the campaign from running.
  • cancelled – Manually stopped and will not resume.
Each associated campaign contact has its own status (pending, scheduled, completed, failed, etc.), which is what analytics are built from.

​
Scheduling model (high level)

When you schedule a campaign, the engine:
  1. Validates that:
    • The agent is ready (voice synced, etc.).
    • At least one outbound number is available.
    • There is at least one contact.
  2. Distributes contacts across days using:
    • The campaign timezone.
    • working_days (e.g. Mon–Fri).
    • Daily window (start_time, end_time).
    • max_calls_per_day.
  3. Assigns each campaign contact its own scheduled_at timestamp.
  4. A background job wakes up, finds due contacts, and spawns calls respecting concurrency limits.
If you change scheduling settings later (see the Scheduling & Delivery Logic guide), the engine can recalculate scheduled_at for future contacts without disturbing those already completed.

​
Pause, resume, and edits

Truedy supports safe operations on live campaigns:
  • Pause – Stops the scheduler and prevents future calls from firing.
  • Resume – Restarts the scheduler, keeping already completed contacts intact.
  • Edit settings – For many statuses (draft, scheduled, paused, and in some cases active), you can adjust windows, caps, and even which days to call.
The detailed semantics (which rows change and when) are covered in:

​
Monitoring and analytics

For each campaign you can see:
  • Total contacts, completed, failed, voicemail, no-answer.
  • Average call duration, total minutes and cost.
  • A per-contact view with call outcomes and error reasons.
You can access these via:
  • The batch-calling dashboard.
  • /batch-calls/{id}/analytics in the Public API.
  • Webhooks (e.g. batch.status.changed, batch.completed).
For analytics endpoints, see Get Batch Call Analytics.

​
When to use campaigns vs single calls

Use single calls (POST /calls) when:
  • You trigger calls one-by-one based on user actions or events.
  • Volumes are small or sporadic.
Use campaigns when:
  • You need to call many contacts on a schedule.
  • You care about pacing, daily caps, and time-of-day targeting.
  • You want consolidated analytics for a specific initiative.

​
Next steps