iCallAgent

Appearance

Create a campaign​

POST
/campaigns/

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.

Authorizations​

ApiKeyAuth

Personal API key. Code samples use Authorization: Bearer <token> — replace <token> with your key from Settings → API Keys (include the word Bearer).

Type
HTTP (bearer)
or
oauth2

OAuth2 access token from the consent flow third-party apps go through (see /oauth/authorize/). Interchangeable with a personal API key on every operation below — both are sent as a Bearer token in the same header.

authorizationCode Flow
Authorization URL"/oauth/authorize/"
Token URL"/oauth/token/"
Scopes:
  • "campaigns:read"List your call campaigns
  • "campaigns:write"Create new call campaigns
  • "contacts:write"Create contacts and queue calls into your campaigns

Request Body​

application/json

Human-readable campaign name. 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).

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

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.

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

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

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

Default0

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

Default30

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.

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

Format"date"

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

Format"date"

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

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

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.

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.

Format"date"

Responses​

application/json
JSON
{
  
"campaign_id": 12,
  
"name": "Q3 Renewals",
  
"status": "draft",
  
"max_concurrent_calls": 3
}

Playground​

Server
Authorization
Body

Samples​

Powered by VitePress OpenAPI