Call Us Today! 877.742.2583

Page tree
Skip to end of metadata
Go to start of metadata


Time of day routing allows calls to be sent to different extensions based upon the time of day, day of week and in some cases, holidays. As of SVN revision 14385, FreeSWITCH supports a number of matchable variables for time and date elements. These are discussed in the Dialplan XML wiki page. The new matching variables obviate the need for using the strftime API. (You may still use strftime if you so choose or if you have a specific need that only strftime meets.)

 Click here to expand Table of Contents


AttributeAcceptable ValuesDescription
year0 - 9999calendar year
yday1 - 366day of year
mon1 - 12month (Jan = 1, etc.)
mday1 - 31day of month
week1 - 53week of year
mweek1 - 6week of month
wday1 - 7day of week, numeric (sun = 1, mon = 2, etc.)








day of week

hour0 - 23hour
minute0 - 59minute (of the hour)
minute-of-day1-1440minute of the day (midnight = 1, 1am = 60, noon = 720, etc)

time range

Example: 08:00-17:00


time range, with seconds

date-timeYYYY-MM-DD hh:mm~YYYY-MM-DD hh:mm

date time range, note the ~ delimiter

Example: 2010-10-01 00:00:01~2010-10-15 23:59:59

YYYY-MM-DD hh:mm:ss~YYYY-MM-DD hh:mm:ssdate time range, with seconds, note the ~ delimiter


These can be combined in the same condition, e.g:


Time and date variables support wrap-around to span the changing of the days, months, or years:

(warning) If you use wrap-around then the from and to date/time need to be one value lower so 5:00:00-5:00:00 will read as 0 and needs to be 5:00:00-4:59:59 which would then read as 5AM from today to 4:59AM tomorrow.


Comma–separated values allow discrete blocks of time to be specified:

(warning) the tilde ~ character is used to delimit the starting date time and the ending date time

Time Zone Manipulation

By default, time–based routing uses the local time kept by FreeSWITCH. If you want to use a different time zone, you have 2 options (as of 2012-11-01 in master, see  FS-4741 - timezone doesn't seem to work in time based conditions (tod_tz_offset and tz-offset) Closed ).


string Sets the timezone for this particular call. Can be used, e.g., to set the timezone for a caller who is checking his/her voicemail. The value is expressed in Linux timezone format (ex. America/New_York -- see /usr/share/zoneinfo/ for the standard list of Linux timezones).

(warning) this variable must actually be set before the comparison, so either set it inline, transfer, or set it in the user directory.

See also: Time of Day and Holiday Routing.


You can set the time zone globally for Freeswitch in /conf/vars.xml

Specify the timezone in the dialplan:

In the directory:


integer Sets the GMT offset to be used on this call for time of day conditions.

(warning) this variable must actually be set before the comparison, so either set it inline, transfer, or set it in the user directory.


To set the offset global in conf/vars.xml:


The examples presented here can be added to the conf/dialplan/default.xml file or you can create a new file in conf/dialplan/default/ to be included in the default dialplan (see the bottom of the vanilla default dialplan).

Provision an internal extension # for Sales to route calls dialed for 2002.


Setup variables prior to transferring to call handler for sales. This sets the variables so that they will be available to the condition test during the next pass through the dialplan initiated by the transfer app.


Handle Sales Call

If Sales is open then route to extension first, then vMail; else send call directly to vMail. In this example, Sales have their own mailbox (#2001) - the configuration of that box forwards all vMail to email and does not store a local copy.


VoiceMail Config (in conf/directory/default/2001.xml)

Voicemail config



Office Hours

Example for office open 09:00-16:00

Has inbound DID routed to extension 5001. Because the office_status variable is set with the inline attribute, the variable takes effect immediately with no need to transfer to another extension definition. The following dialplan extension will always be executed and continue after matching.

Time and day evaluation

This extension will be evaluated if 5001 is the destination number and will build a final destination consisting of 5001_open or 5001_closed.

Ext. 5001

Now the call is handled.

Open/closed call handler


Holiday Routing

Similar to time of day routing, holiday routing can be used to route calls when your office is closed due to various company or national holidays.

Often these holidays fall on consistent dates and you can use the mday and mon attributes to detect them. Here is Christmas for example:

Fixed date

However, some holidays don't fall on consistent dates and are instead something like 'the third Monday in February'. You can use the mweek (week of month) condition parameter (added in r15723) to help with this:

Third Monday

Sometimes, again, a holiday is specified as something like the 'last Monday in October' and you have to do something like this:

This works because the last Monday in October is guaranteed to fall in the last 7 days of the month (the 25th to the 31st) and this condition doesn't pass unless everything evaluates to true.

Using these three patterns you can match almost any holiday date, however, there are complicated ones like Easter and Inauguration Day that are more complicated and would require some custom coding to detect.

Memorial Day

Memorial Day

There are more examples in the default dialplan that cover all US federal holidays except for inauguration day.