DEV Community

Jason Shouldice
Jason Shouldice

Posted on • Edited on • Originally published at vicistack.com

How VICIdial's Timezone System Works (and Where It Breaks)

#voip #asterisk #sysadmin #devops

One TCPA violation is $500 per call. Willful violations hit $1,500. A single dialing session that calls 200 leads outside safe hours could generate $100,000-$300,000 in liability. And the #1 cause I see in audits? Timezone misconfiguration.

VICIdial has built-in timezone detection. Most people assume that means it's handled. It's not. Most installations have gaps — missing state rules, wrong DST handling, or call_time definitions that don't cover edge cases.

How VICIdial Determines a Lead's Timezone

The system maps each lead's postal code to a GMT offset using the vicidial_postal_codes table. When the hopper evaluates a lead for dialing:

  1. Read the lead's postal code
  2. Look up GMT_offset and DST flag
  3. Calculate local time (if DST=Y and currently within DST range, add 1 hour)
  4. Compare against the campaign's call_time definition
  5. Only add to hopper if local time falls within the permitted window

The gmt_offset_now field in vicidial_list stores the lead's current GMT offset including DST adjustment. This is what the hopper actually uses. If it's wrong, leads get dialed at the wrong time regardless of your call_time settings.

The Indiana and Arizona Problems

Indiana has counties in both Eastern and Central time zones. If your vicidial_postal_codes table doesn't differentiate them, all Indiana leads get assigned Eastern time, and you call Central Indiana leads an hour early. Gary (464xx) and Evansville (476xx-477xx) are Central. Indianapolis is Eastern.

Arizona doesn't observe DST — except for the Navajo Nation, which does. During DST months, Arizona is the same as Pacific Daylight Time, not Mountain Daylight. VICIdial typically handles this as a fixed offset, but verify your timezone data accounts for the DST non-participation.

Configuring call_time and state_call_time

Create your base calling window in Admin > Call Times:

Call Time ID: TCPA_STANDARD
Default Start: 800  (8:00 AM)
Default Stop: 2100  (9:00 PM)
Enter fullscreen mode Exit fullscreen mode

For states with stricter hours, use State Call Times (Admin > Call Times > State Call Times):

  • Oklahoma: Stop at 2000 (8:00 PM)
  • Washington: Stop at 2000 (8:00 PM)
  • Texas Sunday: Start at 1200 (Noon)

VICIdial evaluates both call_time AND state_call_time. The more restrictive rule wins.

DST Transitions Are Dangerous

On the "spring forward" Sunday, there's a window where some leads might have stale timezone data because the hopper recalculation doesn't update instantly for all leads.

The fix: add a safety buffer. Use 8:05 AM to 8:55 PM instead of 8:00 AM to 9:00 PM. The cost is 10 minutes of reduced dialing per day. The benefit is protection during DST transitions and clock skew. Many compliance-conscious centers use this buffer year-round.

Also run chronyc tracking or ntpq -p to verify your server's NTP sync. If your clock drifts even 5 minutes, you could be dialing early or late.

Audit Your Data

Before trusting your timezone setup, check for leads with missing timezone data in your active lists. Leads without a postal code have no timezone protection — VICIdial will either skip them (safe) or assign a default (potentially unsafe).

The week before each DST transition (March and November), verify that Arizona and Hawaii postal codes show DST=N, and that your active campaigns have correct Call Time assignments.

Key Takeaways

  1. Never rely on VICIdial defaults. Configure call_time and state_call_time explicitly.
  2. Add a time buffer. 10 minutes of lost dialing is insignificant compared to one violation.
  3. Validate postal code data on lead import. No zip code means no timezone protection.
  4. Track DST transitions. Verify timezone data the Monday after each transition.
  5. Use NTP. Clock drift causes compliance failures.
  6. Document everything. If you can't prove compliance, you weren't compliant.

ViciStack manages TCPA-compliant timezone dialing for VICIdial call centers, including postal code validation, DST transition management, and daily compliance auditing. $150/agent/month, all included.

Originally published at https://vicistack.com/blog/vicidial-timezone-dialing-tcpa/

Top comments (0)