Time conditions

Any step can carry a when: block. If it does not match, the step is skipped and the plan continues with the next one.

- id: greeting
  type: play
  file: ../../../sounds/welcome.wav
  when:
    days: [mon, tue, wed, thu, fri]
    hours: "09:00-17:30"
    dates: ["2026-12-25", "2026-12-30..2027-01-01"]
    timezone: Europe/Amsterdam
    not: false

Field	Format	Meaning
days	mon tue wed thu fri sat sun	Weekdays the condition matches.
hours	"HH:MM-HH:MM"	A daily window. May wrap midnight.
dates	"YYYY-MM-DD" or "YYYY-MM-DD..YYYY-MM-DD"	Specific dates or inclusive ranges.
timezone	IANA name	Overrides the tenant timezone for this condition.
not	boolean	Inverts the whole result.

How it evaluates

All configured parts must match. An omitted part is not a constraint, so hours alone matches that window on every day of the year.

• days matches when the weekday is in the list.
• hours is inclusive of the start and exclusive of the end: "09:00-17:30" matches at 09:00:00 and at 17:29:59, but not at 17:30:00.
• hours wraps midnight when the start is later than the end: "22:00-06:00" matches from 22:00 through 05:59.
• dates matches when the date falls inside any listed date or range. Ranges are inclusive on both ends, and a range whose end precedes its start is a configuration error.
• not: true inverts the final result, after everything else has been combined.

The timezone resolves as: the condition's own timezone, then the tenant's, then the global timezone, which itself defaults to the system local zone.

The clock is read once per call

All conditions in one dialplan run are evaluated against the same instant, sampled when the plan starts. A call that begins just before a boundary keeps the behaviour it started with.

Patterns

Office hours

when:
  days: [mon, tue, wed, thu, fri]
  hours: "09:00-17:30"

Out of hours — the same condition, inverted

when:
  days: [mon, tue, wed, thu, fri]
  hours: "09:00-17:30"
  not: true

Note that inversion applies to the combination: this matches any time that is not a weekday within the window — so it matches weekends in full, and weekday evenings.

In most plans you do not need this at all: put the office-hours dial first and the announcement after it, and the fall-through rule handles the rest.

Holidays

- id: holiday-notice
  type: play
  file: ../../../sounds/holiday.wav
  when:
    dates: ["2026-12-25", "2026-12-26", "2026-12-30..2027-01-01"]

- id: office-hours
  type: dial
  when:
    dates: ["2026-12-25", "2026-12-26", "2026-12-30..2027-01-01"]
    not: true
    days: [mon, tue, wed, thu, fri]
    hours: "09:00-17:30"
  target: {kind: ring_group, group: reception}

Reading the second condition carefully: not: true inverts everything, so this matches when it is not (a listed date and a weekday and within hours). If you want "a weekday in hours, but not a holiday", express the holiday exclusion as an earlier step that hangs up or plays an announcement — inverting a multi-part condition rarely means what it looks like it means.

Night handling across midnight

- id: night-service
  type: dial
  when:
    hours: "22:00-06:00"
  target: {kind: external, number: "+31612345678"}

A different timezone for one step

when:
  days: [mon, tue, wed, thu, fri]
  hours: "09:00-17:00"
  timezone: America/New_York

Useful for a tenant whose support desk follows a customer's business hours rather than its own.

Validation

Compilation happens at startup, so a bad condition never reaches a call. It rejects: an unknown day name, an hours value that is not two HH:MM times, a date that is not YYYY-MM-DD, a range whose end precedes its start, and a timezone the system cannot load.