Home > telephony > nts > example-scenarios > func.telecoms.dayparting.edit
function telecoms.dayparting.edit

See also:

Used to edit an existing dayparting.

Apart from having a daypartingID argument with which to identify the dayparting you wish to edit, the arguments are identical to those in ?php print funclink('telecoms.dayparting.create'); ?>, although with the calendar argument you only need to specify the days you wish to change.

You must specify the daypartingID argument, and if (and only if) you're editing a dayparting in a sub-account, you need to specify the custID argument to identify the sub-account. Other than that, all other arguments are optional. You only need to supply arguments for the elements you wish to change, though you may provide the full set if you wish.

The calendar argument, if specified, may only contain some days. These days will be changed but all others will be left as they were.

Note that whilst all of the arguments (apart from daypartingID) are optional, the dayparting must remain consistent with itself. This means for example that if you decide to update the destinations by supplying a new list of destinations in the dests argument and in doing so you fail to provide one with a destseq value that is referenced in some of the calendar segments, the API will disallow the edit and instead return an error.

Arguments:

argrequired?syntaxinfo
daypartingIDYposintIdentifies the dayparting you wish to edit
destsNlist:assocA list of destinations (eg phone numbers, voicemails, etc) that calls can be sent to depending on the day and time
calendarNlist:assocAn object containing a list of days of the week and within those, the routing choices for different times of the day
descNstringA short textual description of the dayparting object
timezoneNstringThe time zone local to the users/customers who will be using this dayparting; defaults to Europe/London
holiday_likeNenum:monday|tuesday|wednesday|thursday|friday|saturday|sundayThe day of week in your calendar that public holidays should behave like
holiday_regionsNlist:stringA list of regions whose public holidays apply to those who will be receiving calls via this dayparting
custIDNposintcustID of the account that owns the dayparting being edited (defaults to the current account). You only need to specify this if you are editing a dayparting in a sub-account.

Further argument information

daypartingID

The daypartingID argument identifies which dayparting you wish to edit. This will be the daypartingID value returned by telecoms.dayparting.create when the dayparting was created. It is also returned by telecoms.dayparting.list.

dests

see telecoms.dayparting.create:dests

calendar

This argument matches the same named argument in telecoms.dayparting.create desribed at telecoms.dayparting.create:calendar but with the exception that you don't have to supply all days of the week. Any days you supply will be changed to match what you specify but any days you omit will remain unchanged.

desc

see telecoms.dayparting.create:desc

timezone

see telecoms.dayparting.create:timezone

holiday_like

see telecoms.dayparting.create:holiday_like

holiday_regions

see telecoms.dayparting.create:holiday_regions

Example 1

Calling telecoms.dayparting.get to fetch a dayparting's detail, calling telecoms.dayparting.edit to change it and then calling telecoms.dayparting.get again to confirm the changes.

Fetching the day parting prior to editing it:

telecoms.dayparting.get returns the dayparting definition within the "results" sub-object.

You will note that the time segments have the time in hours minutes and seconds, not just hours and minutes. This is how dayparting time segments are stored internally. When specifying time segments, you may put the seconds on if you wish, but if you don't then the seconds will be assumed to be :00.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.dayparting.get",
   "args" : {
      "daypartingID" : 2850
   }
}

JSON example response:

{
   "results" : {
      "custID" : 16526,
      "daypartingID" : 2850,
      "desc" : "DP test",
      "dests" : [
         { "destseq" : 1, "dest_type" : "ddi", "ddi" : "+441276500500" },
         { "destseq" : 2, "dest_type" : "voicemail", "mailboxID" : 1649 }
      ],
      "calendar" : {
         "monday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "tuesday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "wednesday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "thursday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "friday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "saturday" : [
            { "starttime" : "00:00:00", "destseq" : 2 }
         ],
         "sunday" : [
            { "starttime" : "00:00:00", "destseq" : 2 }
         ]
      },
      "holiday_like" : "sunday",
      "holiday_regions" : [
         "UK/England and Wales"
      ],
      "timezone" : "Europe/London"
   },
   "success" : 1
}

Editing the day parting:

It has been decided that voicemails have been going to the wrong mailbox so a new voicemail mailbox with mailboxID 2388 has been created with the telecoms.voicemail.mailbox.create function. It is therefore necessary to re-send the dests argument to redefine the destinations so that the mailboxID can be updated in the dayparting.

Also, management have decided that their workers can go home earlier on Fridays, but for some inexplicable reason want to make them wait 15 seconds after 16:30 before they can clock off. As this is the only day whose time segments are being changed, you only need to redefine friday within the calendar argument.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.dayparting.edit",
   "args" : {
      "daypartingID" : 2850
      "dests" : [
         { "destseq" : 1, "dest_type" : "ddi", "ddi" : "01276500500" },
         { "destseq" : 2, "dest_type" : "voicemail", "mailboxID" : 2388 }
      ],
      "calendar" : {
         "friday" : [
            { "starttime" : "00:00", "destseq" : 2 },
            { "starttime" : "09:00", "destseq" : 1 },
            { "starttime" : "16:30:15", "destseq" : 2 }
         ]
      }
   },
}

There is no data to return so the API just returns a success indication:

JSON example response:

{
   "results" : {},
   "success" : 1
}

Re-fetching the day parting to see the changes:

You can now see the latest changes incorporated within the dayparting:

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.dayparting.get",
   "args" : {
      "daypartingID" : 2850
   }
}

JSON example response:

{
   "results" : {
      "custID" : 16526,
      "daypartingID" : 2850,
      "desc" : "DP test",
      "dests" : [
         { "destseq" : 1, "dest_type" : "ddi", "ddi" : "+441276500500" },
         { "destseq" : 2, "dest_type" : "voicemail", "mailboxID" : 2388 }
      ],
      "calendar" : {
         "monday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "tuesday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "wednesday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "thursday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "17:00:00", "destseq" : 2 }
         ],
         "friday" : [
            { "starttime" : "00:00:00", "destseq" : 2 },
            { "starttime" : "09:00:00", "destseq" : 1 },
            { "starttime" : "16:30:15", "destseq" : 2 }
         ],
         "saturday" : [
            { "starttime" : "00:00:00", "destseq" : 2 }
         ],
         "sunday" : [
            { "starttime" : "00:00:00", "destseq" : 2 }
         ]
      },
      "holiday_like" : "sunday",
      "holiday_regions" : [
         "UK/England and Wales"
      ],
      "timezone" : "Europe/London"
   },
   "success" : 1
}

Example 2

It later transpired that the user works in Scotland and follows Scottish public holidays, not those in England and Wales. So now it's necessary to call telecoms.dayparting.edit to change the holiday_regions list. See publicholiday.region.list for a list of supported regions.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
   "func" : "telecoms.dayparting.edit",
   "args" : {
      "daypartingID" : 2850,
      "holiday_regions" : [
         "UK/Scotland"
      ]
   },
}

JSON example response:

{
   "results" : {},
   "success" : 1
}