Reusable calling windows, timezones, retry policy, and the agent to dial with.
A configuration is an org-level, reusable bundle that a campaign points at. It defines when contacts may be called (calling windows per timezone), how aggressively to retry, how to normalize uploaded phone numbers, and which agent version does the dialing. Create a configuration once and reuse it across many campaigns.A configuration has three parts:
Schedule — when calls are allowed, by timezone.
Dialing policy — retry limit and the default country code for normalizing numbers.
The schedule controls which timezones are inside their calling window at a given moment. Calls are only placed to contacts whose timezone is currently in a window.
Field
Type
Default
Description
default_timezone
string (IANA)
America/New_York
Fallback timezone for contacts that do not carry one. Must be a valid IANA identifier.
default_windows
TimeWindow[]
[]
Calling windows used for regular contacts and all retries. An empty list means no calls are allowed.
overrides
ScheduleOverride[]
[]
Per-timezone window lists that replace default_windows for the listed timezones.
scheduled_windows
TimeWindow[] | null
null
Windows used only for first-time scheduled contacts. When null, falls back to default_windows.
scheduled_overrides
ScheduleOverride[] | null
null
Per-timezone windows for first-time scheduled contacts. When null, falls back to overrides.
A TimeWindow is a set of weekdays plus a daily start and end time.
Field
Type
Description
days
string[]
One or more of mon, tue, wed, thu, fri, sat, sun.
start
string
Start time in 24-hour HH:MM (hour 0-23, minute 0-59).
end
string
End time in 24-hour HH:MM. Must differ from start.
If start is earlier than end, the window is a normal same-day range (for example 09:00-17:00). If start is later than end, the window crosses midnight (for example 22:30-03:30), and the early-morning portion is attributed to the previous day’s days entry.
If default_windows is empty and no override matches a contact’s timezone, no calls are placed to that contact. Set at least one window before launching a campaign.
A ScheduleOverride attaches a list of windows to one or more timezones. For any contact in a listed timezone, these windows replace default_windows entirely.
Field
Type
Description
timezones
string[]
IANA timezone identifiers this override applies to.
There are two parallel sets of windows. Use scheduled windows when you want first-time scheduled contacts to be dialed on a different schedule than everyone else.
Window set
Applies to
Falls back to
default_windows / overrides
Regular contacts and all retries
(none)
scheduled_windows / scheduled_overrides
First-time scheduled contacts only
default_windows / overrides when null
To list every valid IANA timezone identifier accepted by these fields, call:
How many times a single phone number may be dialed before it is exhausted.
default_country_code
string
+1
+ followed by 1-4 digits
Country code applied when normalizing uploaded numbers to E.164.
When contacts are uploaded against a campaign, numbers without an explicit country code are parsed using default_country_code and formatted to E.164 (for example, +44). Numbers that cannot be parsed are reported as invalid. See Contacts for upload behavior and Dialing and retries for how attempts are spent.
A configuration can be marked as the organization’s default with is_default. Only one default may exist per organization.
Creating or updating a configuration with is_default: true while a default already exists returns 409 Conflict. Un-default or delete the existing default first.
