Campaigns overview

A campaign is a managed bulk-outbound batch: a CSV of contacts + a target agent + a telephony configuration + per-campaign concurrency, retry, scheduling, and circuit-breaker rules. zoxaAI dispatches calls, respects all the limits, and records every important state transition as a structured logs[] entry on the campaign — you call start, then poll progress / runs (or read logs[]) for visibility.

Lifecycle

created → syncing → running → (paused | completed | failed)
                       ↑              ↓
                       └── resume ─────┘

pause works only while running. resume works from either paused or failed — both are recoverable, and resume revalidates wallet + telephony first. Transient trouble while dialing (repeated batch errors, a drained phone-number pool) pauses the campaign, so failed is reserved for unrecoverable setup errors (e.g. a CSV sync failure). Completion is exact: a campaign moves to completed the moment its last call's outcome lands.

Endpoints

Target agent

Every campaign targets one agent. Pass the agent's public uuid as agent_uuid when you create the campaign; each contact is called by that agent's pipeline. The campaign response reports the resolved agent as agent_id (internal integer id) and agent_name. The target can't be changed after creation.

CSV source

Campaigns are CSV-only. Contacts come from a previously-uploaded CSV file (via Files or the campaign create form). Required: a phone_number column. Optional: any number of template-variable columns — referenced from your agent prompt as {{column_name}}.

Telephony configuration

Each campaign is bound to a specific telephony configuration — the provider account and outbound phone-number pool it dials from. Pass telephony_configuration_id on create to pick one explicitly, or omit it to inherit the org's default.

Concurrency, retry, schedule, circuit breaker

All four are optional structured configs on create / update:

Structured event logs

Every campaign carries an append-only logs[] array in its API response. The orchestrator, circuit breaker, source-sync, and phone-pool-exhaustion handler all write structured entries to it — so operators can see why a campaign moved to paused or failed without trawling server logs.

Each entry has:

Common event identifiers:

Related

• Calls overview
• Agent config — defines what each campaign call runs