telecoms.dayparting.create function

You must define a list of destinations within the dests argument, and then with the calendar argument you define the times that calls should route to your defined dests, identifying the dest by the destseq value.

Arguments:

arg	required?	syntax	info
`dests`	Y	list:assoc	A list of destinations (eg phone numbers, voicemails, etc) that calls can be sent to depending on the day and time
`calendar`	Y	list:assoc	An object containing a list of days of the week and within those, the routing choices for different times of the day
`desc`	N	string	A short textual description of the dayparting object
`timezone`	N	string	The time zone local to the users/customers who will be using this dayparting; defaults to Europe/London
`holiday_like`	N	enum:monday\|tuesday\|wednesday\|thursday\|friday\|saturday\|sunday	The day of week in your calendar that public holidays should behave like
`holiday_regions`	N	list:string	A list of regions whose public holidays apply to those who will be receiving calls via this dayparting
`custID`	N	posint	custID of the account for which this dayparting should be created for (defaults to the current account). You only need to specify this if you are creating a dayparting in a sub-account.

Further argument information

dests

The dests argument defines all of the places the calls routed in to this dayparting can be forwarded to. It should contain an array of assoc/objects, each defining:

destseq - an integer value which you also use in the calendar argument to define which defined destination each time segment should use. This number sbould be between 1 and 255 inclusive and be unique across all of the destinations defined in the dests argument.
dest_type describes the destination item type, and can be one of:
- "ddi" for sending calls to a destination phone number (DDI); requires the ddi parameter
- "routeplan" for sending calls to a routeplan; requires the routeplanID parameter
- "voicemail" for sending calls to voicemail; requires the mailboxID parameter
ddi contains a destination phone number - required if dest_type is "ddi"
routeplanID contains a routeplanID - required if dest_type is "routeplan"
mailboxID contains the ID of a voicemail mailbox - required if dest_type is "voicemail"

Note that although dayparting is currently unable to route calls to many of our supported destination types (eg SIP addresses, IVR menus etc), routeplans can route to all of these things, so you can solve that issue by setting up a routeplan to route to the required destination and then using that routeplan in your dayparting.

An example dests list is below. Not that each object in the list has its own unique destseq value. In this example, two destinations are defined. The first defines a ddi destination which means that calls will be forwarded to the phone number defined in the ddi parameter. The second defines a routeplan destination, which means that any time segments that point to this destination will go to wherever the specified routeplan is configured to route. See the telecoms.routeplan functions for more information on routeplans.

      "dests" : [
         {
            "destseq" : 1,
            "dest_type" : "ddi",
            "ddi" : "+441276459940"
         },
         {
            "destseq" : 2,
            "dest_type" : "routeplan",
            "routeplanID" : 78697
         }
      ],

calendar

The calendar argument is an object with seven lists of time segments, each time segment being keyed by the weekday name to which those segments apply.

With telecoms.dayparting.create you MUST specify every weekday in the calendar. However, when calling telecoms.dayparting.edit, you MAY specify each day if you wish, but you only NEED to specify days whose time segments you wish to change. You must, however, when specifying a day's segments, always define all of the segments for that day.

Each time segment defines these two things:

starttime - the starting time of this time segment. This is the time of the day in HH:MM format, or optionally HH:MM:SS format. The 24 hour clock is used, so for PM times, use hours 12 to 23. This time segment is assumed to run up to the wallclock second before beginning of the next time segment for this day, if defined, otherwise 23:59:59.
destseq - this number must either match the destseq value defined in one of the destinations defined in the dests argument, or can be null. If it is null then calls arriving during this time will be given a busy/engaged signal. Otherwise, the calls will route to the destination that is defined in the corresponding dests item.

In the example calendar below, weekdays have all been given the same definition. Assuming that this corresponds to the dests example above, this means that on each weekday from midnight to 9am callers will hear a busy/engaged tone, from 9am to 6pm they will be routed to 01276459940 because this is where the destination with destseq=1, and then from 6pm they'll again be presented with a busy tone.

On Saturdays, callers will get a busy/engaged tone unless they call between 9am and midday in which case their call will be routed to wherever routeplan 78697 goes to. This is because there the middle time segment for that day starts at 09:00:00 and specifies destseq=2. In the dests argument, the destination with destseq=2 is defined as routing to routeplan 78697. The last Saturday time segment starts at 12:00:00 so this implicitly ends the previous time segment and, because destseq=null in this final Saturday segment, ensures that any calls coming in during this time receive a busy/engaged signal.

Calls to this dayparting on Sundays will receive a busy/engaged tone regardless of the time because there is only one time segment defined for Sundays, and destseq=null for this segment.

"calendar" : {
  "monday" : [
    { "destseq" : null, "starttime" : "00:00:00" },
    { "destseq" : 1, "starttime" : "09:00:00" },
    { "destseq" : null, "starttime" : "18:00:00" }
  ],
  "tuesday" : [
    { "destseq" : null, "starttime" : "00:00:00" },
    { "destseq" : 1, "starttime" : "09:00:00" },
    { "destseq" : null, "starttime" : "18:00:00" }
  ],
  "wednesday" : [
    { "destseq" : null, "starttime" : "00:00:00" },
    { "destseq" : 1, "starttime" : "09:00:00" },
    { "destseq" : null, "starttime" : "18:00:00" }
  ,
  "thursday" : [
    { "destseq" : null, "starttime" : "00:00:00" },
    { "destseq" : 1, "starttime" : "09:00:00" },
    { "destseq" : null, "starttime" : "18:00:00" }
  ],
  "friday" : [
    { "destseq" : null, "starttime" : "00:00:00" },
    { "destseq" : 1, "starttime" : "09:00:00" },
    { "destseq" : null, "starttime" : "18:00:00" }
  ],
  "saturday" : [
    { "destseq" : null, "starttime" : "00:00:00" },
    { "destseq" : 2, "starttime" : "09:00:00" },
    { "destseq" : null, "starttime" : "12:00:00" }
  ],
  "sunday" : [
    { "destseq" : null, "starttime" : "00:00:00" }
  ]
},

desc

This is just a short textual description. It is optional, but is returned by telecoms.dayparting.list and is useful for showing to users when viewing their daypartings.

timezone

This argument can be useful if you wish the time definitions in the calendar argument (ie the day names and starttime values to correspond to the day and time in other time zones. The default (if this is not specified) is UK localtime (which is the timezone "Europe/London"). For example, if you (or your customer, if this is for them) are located in Sydney, you would want to set this argument to "Australia/Sydney". See timezone.list for how to fetch a list of supported timezones.

holiday_like

Use this argument in conjunction with holiday_regions else it will have no effect.

This argument defines which weekday (as defined in the calendar argument) a public/bank holiday should mimic. For example, if you set this argument to "saturday", then if it is currently a public holidays in any of the regions you've listed in the holiday_regions argument, the calendar will mimic the time segments that you've defined for saturdays.

holiday_regions

Use this argument in conjunction with holiday_like else it will have no effect.

This argument should contain a list of one or more geographical regions. If, on the day a call arrives, it is a public holiday in one or more of the geographical regions defined in this argument, AND you have defined the holiday_like argument, then the calendar will mimic the time segments for the day of week specified in holiday_like.

Note that it is sensible to ensure that the timezone argument tallies with holiday_regions in a meaningful way. Whilst the API won't stop you defining a dayparting with holiday regions in Canada and a timezone for Australia/Sydney, such a setup would likely not do what is desired.

For example, if you were to specify holiday_regions as this:

    [
      "UK/England and Wales",
      "UK/Scotland"
    ]

and had set holiday_like to "sunday", then any calls made to this dayparting on a day that happens to be a public/bank holiday in England & Wales or Scotland would use the time segment definitions of Sundays, which in this example would always present a busy/engaged tone.

See publicholiday.region.list for a list of available holiday regions.

Example 1

Creating a dayparting that routes to the main office number from 9am to 5pm on Monday to Friday, and directs the caller to voicemail at all other times. You would previously have used telecoms.voicemail.mailbox.create to create a voicemail mailbox, which in this example would have returned 1649 as the mailboxID. You can see this referenced in one of the destinations defined in the dests argument.

As the desired behaviour for all of the days Monday to Friday is the same, the calendar segments for these days have the same list of segments for each of these days. Saturday and Sunday just have one entry, starting at midnight and lasting the whole day. In this example, calendar segments with destseq 1 route calls to 01276500500, and segments with destseq 2 divert to mailboxID 1649.

timezone is set to Europe/London which is UK local time. This means that the start times in the calendar segments correspond to UK local time for this day parting. See timezone.list for a list of supported timezones.

holiday_regions contains just one region, UK/England and Wales, so only when it's a public holiday in this region does the holiday_like setting come into effect. You may specify multiple regions if you wish. If you do this, then the holiday_like setting will come into effect if it is currently a public holiday in any of the specified regions. See publicholiday.region.list for a list of supported holiday regions.

holiday_like specifies the day in the calendar which public holidays should mimic. In this example, it is set to sunday, so during a public holiday (as per this example in UK/England and Wales) calls will be diverted to voicemail all day, as that is how sunday is defined here.

The response returns the daypartingID which you will need to use in all subsequent API calls if you wish to refer to this dayparting. This could be when you want to edit, get or delete this day parting, or route one of your phone numbers to this dayparting with telecoms.num.route or perhaps create an IVR menu with telecoms.ivr.create which routes callers to this day parting if they choose a particular menu option.

You can use telecoms.dayparting.list to fetch a list of your existing daypartings. This will include, amongst other data, the textual description supplied in the desc argument when you created the dayparting, and the daypartingID of each dayparting.

Example 2

In this example we're creating a day parting for an organisation's Canada office, based in Quebec. We have therefore set holiday_region to Canada/Quebec and timezone to Canada/Eastern so that the times and days in the calendar represent the time local to the office.

This time there are a couple of destinations defined to use routeplans, because the calls are not just to go to one destination phone number but instead to hunt across various destination numbers; this behaviour will be defined in the routeplan. See the telecoms.routeplan functions for more information about routeplans.

We also have a destination that redirects the caller to voicemail, and one that redirects the caller to a single Canadian number.

Monday has a different set of time segments to other days as there is a team of people covering the early shift. Tuesday to Thursday are the same but Friday is covered by a team on phone number +18735551291 but they close at 3pm.