campaigns

Create a campaign

name and widget_id are required (400 without either). widget_id / phone_number_id that don't belong to your workspace return 404, not a validation error.

Behaviours that don't show up in a happy-path example:

  • max_concurrent_calls is silently clamped to your workspace's concurrency entitlement, never rejected — the value actually applied is returned in the response, which may be lower than what you sent.
  • An invalid status silently falls back to draft.
  • Unparseable start_date / end_date / start_time / end_time are silently ignored (left unset), not rejected.
  • Leaving all schedule fields unset means the campaign can dial at any time, any day — there is no separate 'always on' flag.
  • If phone_number_id resolves, it also sets the agent's default outbound number as a side effect.
post/campaigns/

Request

  • Base URL: http://127.0.0.1:8000/api/public/v1
  • URL: http://127.0.0.1:8000/api/public/v1/campaigns/
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /oauth/authorize/, token URL /oauth/token/)

Request body

namestring required

Human-readable campaign name. Required.

widget_idinteger required

Agent id from GET /agents/ (Live agents only on that list). Required — a campaign without an agent never places a call. Must belong to your workspace (404 if not).

caller_idstring

Outbound caller ID (E.164 or provider-accepted form). If omitted and phone_number_id is set, defaults to that number's value.

phone_number_idinteger

Id from GET /phone-numbers/. Sets caller_id from that number and also updates the linked agent's default outbound number. 404 if not in your workspace.

statusstring

One of: draft, active, paused, completed, cancelled. Invalid values silently fall back to draft. Only active campaigns are dialed by the scheduler.

max_concurrent_callsinteger

How many concurrent outbound calls this campaign may place. Silently clamped to your account entitlement (never 400). Response returns the value actually applied.

retry_attemptsinteger

How many times to retry after the first failed/no-answer dial (non-negative). Default 0.

retry_delay_minutesinteger

Minutes between retry attempts. Default 30. Only relevant when retry_attempts > 0.

timezonestring

IANA timezone for the dial window (e.g. America/New_York, UTC). Default UTC when omitted. start_time / end_time / weekdays are evaluated in this zone.

start_datestring date

First calendar day the campaign may dial (YYYY-MM-DD). Unparseable values are silently ignored (left unset).

end_datestring date

Last calendar day the campaign may dial (YYYY-MM-DD, inclusive). Unparseable values are silently ignored.

start_timestring

Daily dial window start as HH:MM (24h) in timezone. Unparseable values ignored. Leave both times unset for all-day dialing.

end_timestring

Daily dial window end as HH:MM (24h) in timezone. Unparseable values ignored.

weekdaysstring[]

Days the campaign may dial, as lowercase abbreviations: mon, tue, wed, thu, fri, sat, sun. Example: ["mon","tue","wed","thu","fri"]. Omit for any day.

excluded_datesstring[]

Calendar dates (YYYY-MM-DD) to skip, e.g. holidays. No calls are placed on these days even if they fall in the schedule window.

Response

campaign_idinteger required

Id of the campaign just created.

namestring required

Campaign name as stored (same as request name).

statusstring required

Status after create (draft if omitted/invalid in the request).

max_concurrent_callsinteger required

Concurrency actually applied after clamping to your account entitlement.

Changes

No recorded changes to this operation across all 1 revision of this API.