Launch a campaign
Launch a DRAFT campaign now, which starts real outbound dialing, or pass schedule to start it later: the campaign becomes scheduled and the dialer starts it once that time passes. A SCHEDULED campaign can be launched again to move its start or, without schedule, to start it now; cancel_campaign cancels it. Requires consentConfirmed: true at launch and at every reschedule (you confirm you hold the required calling consents: ACMA / Do Not Call Register) and a caller number: fromNumber, or the campaign's own. It runs the readiness check get_campaign shows and refuses with error not_ready while any blocker remains (an unpublished agent, no caller number, a number in the pool the workspace doesn't own, no pending recipient, a required {{token}} no recipient has, consent unconfirmed), returning readiness: { blockers, warnings } so you can fix every blocker at once. Warnings such as no spend cap or failing campaign-call tests never stop it; call get_campaign first to read them out to the user. Launching never runs a test. Dialing must be enabled server-side for this environment, so on an environment where it is switched off this reports disabled and places no call.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/workspaces/string/campaigns/string/launch" \ -H "Content-Type: application/json" \ -d '{ "fromNumber": "string", "consentConfirmed": true }'{
"campaign": {
"id": "string",
"name": "string",
"status": "string",
"agentId": "string",
"property1": null,
"property2": null
},
"property1": null,
"property2": null
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Get a campaign GET
Read one campaign in full: its config (agent, brief, opener, caller number, dialing rules, calling window, and convertedOutcomes, the outcomes it counts as converted; empty means conversion is not tracked, plus sequence, the call and SMS steps and the outcomes they end in, with each step's delay, attempts, voicemails, double dial, brief or SMS body, and routes; smsWindow, the hours SMS steps send in (null is the standard SMS hours)), per-status recipient counts, and the results analytics: recipients dialed and calls placed, connected, converted, settled, failed, not reached split into no answer, busy and voicemail, the outcome breakdown of connected calls, dials, connects and conversions over time (by hour for a campaign under 36 hours, otherwise by day, in the campaign's time zone), total and average talk time, and spend in AUD cents: spentCents is what the campaign has actually been charged (call minutes, call checks, post-call analysis and transfers, composed voicemails and SMS segments), inflightCents an estimate for calls still in progress, totalCents the two together (what the spend cap is measured against), callCents the expected cost of one call (the campaign's own average once callCentsObserved, before that the agent's rate over three minutes), and perConnectedCents and perConversionCents the spend divided by connected and converted recipients. A draft or scheduled campaign also carries readiness: { ready, blockers, warnings }, the same checklist launch_campaign enforces. Blockers stop a launch: agent_unpublished, from_number_required, from_number_not_owned, no_recipients (never for an autoEnroll campaign, which can start empty), missing_variables (a {{token}} with no fallback in the opener, a voicemail message or an SMS that no pending recipient has a value for), auto_enroll_needs_spend_cap, sms_sender_required (the sequence has an SMS step and no caller number is an Australian mobile, the only kind that can send SMS) and consent_required (always listed here, because consent is confirmed only at launch). Warnings never stop it: variables_partly_missing, auto_enroll_starts_empty, no_spend_cap, calling_hours, sms_hours, no_conversion_outcomes, no_campaign_tests, campaign_tests_not_run, campaign_tests_failing (with the latest pass rate and, in at, the last run time) and voicemail_without_text. Each item has a title, a detail and sometimes an href to the page that fixes it. Pass the campaign id from list_campaigns.
List a campaign's recipients GET
List one campaign's recipients, 50 a page, in the order they were added. Each carries its status, attempt count, last and next attempt times, the latest call's outcome, summary and session id, callbackAt and callbackNote when a callback is booked (outcome callback_scheduled until the dialer places it), and stoppedAt when an operator stopped them. Filter by status, by outcome (the value in each recipient's outcome field, e.g. 'completed', 'voicemail', 'busy', or 'stopped' for recipients stopped with stop_campaign_recipient), to converted recipients only, or search by name or phone. Use get_campaign_recipient for one recipient's full attempt history.