Skip to main content

​
Recipient timezone resolution for quiet hours

Every quiet-hours decision — org gate, campaign fallback window, TCPA voice guard — is computed against the recipient’s local clock. That means the whole posture stands or falls on one question: which IANA timezone did the platform use for this recipient? The individual guides each cover a slice of the answer. This page is the single map: the resolution chain, what happens when it resolves nothing, and how to steer it with per-call overrides and org-level policy.

​
The resolution chain

Resolution runs fewer steps than there are channels, but each step is the same for every channel. First match wins:
  1. An explicit IANA hint — a timezone_override on the preview call, or a recipientTimezone carried on the send — beats every automatic source below.
  2. The NANP area-code map — for +1 numbers, the area code (and, in split states, the full prefix) maps to a single IANA zone such as America/Los_Angeles or America/New_York. This is the step that usually answers for US recipients.
  3. The country-prefix map — for non-NANP numbers, the E.164 country code maps to a representative IANA zone (a capital-city zone for well-known markets). European, Asian, and Latin-American markets resolve here most of the time.
  4. The org default timezone — for recipients without a usable number (email addresses, push tokens), the timezone you set on your organization supplies the clock.
  5. Unresolved — when none of the above produced a zone, the recipient lands on your org’s unknown_timezone_policy, below.
A relocated US mobile number resolves by its area code, not by where the recipient sleeps — if your CRM carries better knowledge, override it (next section) rather than relaxing the policy.

​
When nothing resolves: fail-open vs fail-closed

The unknown_timezone_policy is one of three values, and it is a tenant-owned control you set on your org: Set it in the dashboard under Settings → Voice, or in the quiet_hours block of organization settings over the API (see quiet hours configuration for the scoped PATCH surface and the whole-document-replace warning). The one fail-closed-by-default case. The controls above are yours to tune. The sole exception is the TCPA federal voice dial window for US recipients: campaign and dialer voice to a +1 recipient that resolves no timezone is blocked regardless of your policy, with no tenant-side opt-out — that federal wire is the only guard the platform owns outright. Every other channel, and ad-hoc voice to non-US recipients, follows your configured policy (defaulting to fail-open skip). The quiet-hours preview enumerates the full reason set per channel — unknown_timezone_skip and unknown_timezone_deny are the two this policy produces. Write the org default timezone the same way — it feeds step 4 of the chain, mostly for email and push recipients that carry no phone number.

​
Overriding per call: timezone_override

Preview calls accept a timezone_override parameter, and send paths accept a recipientTimezone hint. Both take an IANA name (America/Phoenix, not UTC-7) and win over every automatic source:
The response’s local_timezone field tells you which source won — echo it in your rollout checklist before launch and compare it against what your CRM expected. Field-by-field semantics for the whole response live on the quiet-hours preview page.

​
DST is a resolution problem, not a window problem

The window is always checked in recipient-local time, so the IANA zone is the thing to verify. Two recurring pitfalls, both resolved by getting the zone right:
  • Arizona and Hawaii never observe DST — a contact field stamped “Mountain” tells you nothing about Phoenix’s offset today. Resolve the zone and use it; the math follows the IANA database through whichever offset is current.
  • Crossover nights change UTC waits, not wall-clock windows — resolves to the same zone before and after. Recheck around each crossover by re-running the preview and confirming the zone name stays the expected IANA name.
Both pitfalls are worked through in quiet hours across DST — including the Arizona/Hawaii special cases, worked timelines for the 2026 March 8 / November 1 crossover dates, and the pre-launch preview procedure.

​
See also