Timed Routes

Timed Routes, also known as temporal routes, allow you to control the route a call takes based on time-of-day parameters.

 

  • Get a list of temporal rules for the account
  •  v1/accounts/{account_id}/temporal_rul
  

Sample Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"3b5826058364c1caee5858609e3e8193",

   "revision":"fe8ed5b7e8ab38a149d140c9baeab68b",

   "data":[

      {

         "id":"d5ffda84d8cf446b3d77c796c83fa92f",

         "name":"Business Hours"

      },

      {

         "id":"a839f372d95ba3bfe91bfe66794d366c",

         "name":"Holiday"

      }

   ]

}

 

 

 

  • Create a new temporal rule
 

v1/accounts/{account_id}/temporal_rules

 

Sample Request

 

 

{

   "data":{

      "time_window_start":0,

      "time_window_stop":86400,

      "days":[25],

      "name":"Holiday",

      "cycle":"yearly",

      "start_date":62586115200,

      "month":12,

      "ordinal":"every",

      "interval":1

   }

}

 

Sample Response

 

 

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"fc2236c669f0d9ed36f8f991f3e701d4",

   "revision":"1-5f4723608df4e783b6bdea4d90bfe1fb",

   "data":{

      "time_window_start":0,

      "time_window_stop":86400,

      "days":[25],

      "name":"Holiday",

      "cycle":"yearly",

      "start_date":62586115200,

      "month":12,

      "ordinal":"every",

      "interval":1

   }

}

 

 

  • Modify an existing temporal rule
 
  • v1/accounts/{account_id}/temporal_rules/{temporal_rule_id}

 

Sample Request

 

 

{

   "data":{

      "time_window_start":0,

      "time_window_stop":86400,

      "days":[

         24,

         25,

         26

      ],

      "name":"Holiday",

      "cycle":"yearly",

      "start_date":62586115200,

      "month":12,

      "ordinal":"every",

      "interval":1

   }

}

 

Sample Response

 

 

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"c1fda600b5a9e9facb347b2dacc4bf0d",

   "revision":"2-5f4723608df4e783b6bdea4d90bfe1fb",

   "data":{

      "time_window_start":0,

      "time_window_stop":86400,

       "days":[

         24,

         25,

         26

      ],

      "name":"Holiday",

      "cycle":"yearly",

      "start_date":62586115200,

      "month":12,

      "ordinal":"every",

      "interval":1

   }

}

 

 

  • Removes a temporal rule, callflows that reference this ID will not be updated but that rule will be ignored.
  • 1

v1/accounts/{account_id}/temporal_rules/{temporal_rule_id}

 

Sample Request

 

 

{

   "data":{

 

   }

}

 

Sample Response

 

 

{

   "auth_token":"{auth_id}",

   "status":"success",

   "request_id":"6cd8933ab69bdd1e9907977ff45704e5",

   "revision":"undefined",

   "data":{

   }

}

 

name

A friendly name used when displaying the rule in the UI

 View Sample Code
 
"name": "Business Hours"

enabled

The current rule status, there are three valid values for this:

Value
Description
true This rule should be considered active, irregardless of the current time/date
false This rule should never be considered active, effectively ignoring it
NULL Depending on the current time/date this rule may be active

Unless you need to override a time of day rule (for example keep an office open longer) this property should not be set.

 View Sample Code
 
"enabled": true

cycle

The cycle type determines the period which the rule cycles, valid options are:

Value
Description
"daily" The rule cycles on a daily basis per the interval
"weekly" The rule cycles on a weekly basis per interval
"monthly" The rule cycles on a monthly basis per interval
"yearly" The rule cycles on a yearly basis per interval
"date" The rule is active once on the start date parameter and does not reoccur
 View Sample Code
 
"cycle": "weekly"

The interval is an integer that controls the cycle period. If not provided it is assumed to be 1 meaning the rule is evaluated each cycle (every day, week, month, or year).

interval

For example if you wanted the rule to be valid every other week you would use the cycle "weekly" with an interval of 2.

 View Sample Code
 
"interval": 1

start_date

This is a date that the rule should be considered invalid prior to, in Gregorian seconds.

This is especially important when using an interval other than 1. For example if the rule should be applied every other year and the start date is in 2010, then it will be active on 2010, 2012, 2014, ect. However, if the start date was in 2011 then it will be active on 2011, 2013, 2015, ect.

It is recommended that a start date always be set to some time in the past if this control is not required to ensure it takes effect on the next cycle.

 View Sample Code
 
"start_date": 62586115200

wtime_start

This is the time that the rule should become active on a date specified. It is in seconds from the start of the day where 0 is the start of a day and 86400 is the end.

 View Sample Code
 
"wtime_start": 32400

 

wtime_end

This is the time that the rule should become inactive on a day specified. It is in seconds from the start of the day where 0 is the start of a day and 86400 is the end.

 

 View Sample Code
 
"wtime_end": 61200

 

wdays

Weekdays is an array of weekday names the rule is valid on. This property is only valid for:

Cycle
Condition
"weekly" If multiple weekdays are provided they must be in order in accordance with ISO 8601
"monthly" Only a single weekday is valid (an array of one element) and an "ordinal" is required
"yearly" Only a single weekday is valid (an array of one element) and an "ordinal" is required

  View Sample Code

 
"wdays": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday",
    "saturday",
    "sunday"
]

 

ordinal

The recurrence ordinal is used with the weekday parameters on monthly and yearly cycles to denote the frequency. Valid ordinals are:

Value
Description
"every" For every occurrence of the provided weekday the rule is considered active
"last" For last occurrence of the provided weekday, depending on the month specified, the rule is considered active
"first" For first occurrence of the provided weekday the rule is considered active
"second" For second occurrence of the provided weekday the rule is considered active
"third" For third occurrence of the provided weekday the rule is considered active
"fourth" For fourth occurrence of the provided weekday the rule is considered active
"fifth"

For fifth occurrence of the provided weekday the rule is considered active

Not all months have a fifth occurrence of a weekday, it this case it will be ignored.

 

 

 View Sample Code
 
"ordinal": "first"

 

month

Month is the numeric month number that a rule is active on and only used by yearly cycles 

 View Sample Code
 
"month": 4

 

days

Days is an array of numeric days of a month which the rule is valid on. This property is only valid with the cycles "monthly" and "yearly". It overrides "wdays" if both are provided. 

 View Sample Code
 
"days": [11, 12, 13]
 View Sample Code
 
{
   "time_window_start":0,
   "time_window_stop":86400,
   "days":[
      24,
      25,
      26
   ],
   "name":"Holiday",
   "cycle":"yearly",
   "start_date":62586115200,
   "month":12,
   "ordinal":"every",
   "interval":1
}

 

Valid Parameters Matrix

  • Date
    • start_date
  • Daily
    • interval + start_date
  • Weekly
    • interval + start_date + multiple wdays
  • Monthly
    • interval + start_date + multiple days
    • interval + start_date + single wdays + ordinal
  • Yearly
    • interval + start_date + month + multiple days
    • interval + start_date + month + single wdays + ordinal

To create a temporal route a node is created to invoke the 'temporal_route' action and the temporal rules are listed as children. Each rule is tested in the order provided using the first active rule or defaulting to the wildcard ("_") rule if no active rules are present.

Property
Description
Validation
Modifiable
action The action that the node should preform, see Temporal Actions   yes
timezone The timezone that the temporal rules should be evaluated in   yes
{
   "data": {
   },
   "module": "temporal_route",
   "children": {
       "a839f372d95ba3bfe91bfe66794d366c": {
           "data": {
               "id": "4aef1b92c509b4a9168c4e4493a1cb29"
           },
           "module": "voicemail",
           "children": {
           }
       },
       "d5ffda84d8cf446b3d77c796c83fa92f": {
           "data": {
               "id": "aa678b9aab3f4cef922a7214655ed475"
           },
           "module": "device",
           "children": {
           }
       },
       "_": {
           "data": {
               "id": "b55cc374541543f9ae98706febd87806"
           },
           "module": "voicemail",
           "children": {
           }
       }
   }
}

When temporal rules are invoked in a callflow there are a number of actions that can be preformed, they are as follows:

Value
Description
enable Enable the first temporal rule (child) in the callflow, its route will be used regardless of the actual time
disable Disable all temporal rules (children) in the callflow, the wildcard node will be used regardless of the actual time
reset Reset all temporal rules (children) in the callflow, this resumes normal operation
menu Provide the caller with a menu to enable, disable or reset the temporal rules in the callflow
any other value Process the listed callflows (children) and route to the first match or the wildcard if none are active