About
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.)
Variables
Attribute | Acceptable Values | Description |
---|---|---|
year | 0 - 9999 | calendar year |
yday | 1 - 366 | day of year |
mon | 1 - 12 | month (Jan = 1, etc.) |
mday | 1 - 31 | day of month |
week | 1 - 53 | week of year |
mweek | 1 - 6 | week of month |
wday | 1 - 7 | day of week, numeric (sun = 1 , mon = 2 , etc.) |
| day of week | |
hour | 0 - 23 | hour |
minute | 0 - 59 | minute (of the hour) |
minute-of-day | 1-1440 | minute of the day (midnight = 1 , 1am = 60 , noon = 720 , etc) |
time-of-day | hh:mm-hh:mm | time range Example: |
hh:mm:ss-hh:mm:ss | time range, with seconds | |
date-time | YYYY-MM-DD hh:mm~YYYY-MM-DD hh:mm | date time range, note the Example: |
YYYY-MM-DD hh:mm:ss~YYYY-MM-DD hh:mm:ss | date time range, with seconds, note the ~ delimiter |
These can be combined in the same condition, e.g:
Wrap-Around
Time and date variables support wrap-around to span the changing of the days, months, or years:
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.
Blocks
Comma–separated values allow discrete blocks of time to be specified:
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
).
timezone
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/zone.tab
for the standard list of Linux timezones). 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.
Usage
You can set the time zone globally for Freeswitch in /conf/vars.xml
Specify the timezone in the dialplan:
In the directory:
tod_tz_offset
integer Sets the GMT offset to be used on this call for time of day conditions. this variable must actually be set before the comparison, so either set it inline, transfer, or set it in the user directory.
Usage
To set the offset global in conf/vars.xml
:
Usage
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)
Examples
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.
This extension will be evaluated if 5001 is the destination number and will build a final destination consisting of 5001_open or 5001_closed.
Now the call is handled.
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:
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:
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
There are more examples in the default dialplan that cover all US federal holidays except for inauguration day.