Home > telephony > nts > example-scenarios > func.telecoms.routeplan.create
function telecoms.routeplan.create

Creates a new route plan. A route plan can be defined to attempt call delivery to one destination and then, if unsuccessful, fall back to a second, etc.

Arguments:

argrequired?syntaxinfo
custIDNposintcustID of account where you want to create a new route plan (defaults to your own account)
descNstringa brief textual description of your route plan
itemsYarrayarray of call destinations; this is where the routeplan can route calls to
modeNenum:sequential|parallel|wtd-single|wtd-rotational|wtd-parallel|rr-rotational|rr-paralleldialling mode; eg try one destination at a time, dial all simultaneously, etc
max_repeatsNunsintMax number of times to re-try the destination list if not answered
busy_actionNenum:busy|busy-any|redialWhat to do when destinations are busy
headstartNunsintnumber of seconds to prioritise one destination in wtd-parallel or rr-parallel mode

Further argument information

items

The items array is an array of destination items. A destination item defines somewhere a phone call might be delivered (eg a phone number) and a duration (eg how long to ring it before moving on to the next item in the route plan).

An entry in the items array consists of 3 main elements:

Destination arguments

This depends on the value of the type element:

mode

Specifies the dialling mode of the diallable destinations in the routeplan. Diallable destinations are destionations that might answer, eg a destination phone number, a SIP address; this is in contrast to destination types that will always answer, eg voicemail.

The modes are:

max_repeats

If all destinations have been attempted and none were answered, the routeplan will go back to the start and try again. This argument can be used to limit the number of times this happens (a value of zero meaning don't repeat at all). Once the maximum number of repeats has been reached, the call is ended.

busy_action

This argument defines what should happen if the destinations are busy. The options are:

headstart

For modes wtd-parallel and rr-parallel, this parameter defines the number of seconds to let the priorirised destination ring for before (if it remains unanswered) all of the other destinations start ringing as well.

Example 1

Create a route plan to try 01234567890 for 15 seconds and if unsuccessful, divert to 01123456789.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
    "func" : "telecoms.routeplan.create",
    "args" : {
       "items" : [
          {
             "arg" : "01234567890",
             "dur" : 15,
             "type" : "number"
          },
          {
             "arg" : "01123456789",
             "type" : "number",
             "dur" : 0
          }
       ],
       "desc" : "test routeplan 1"
    }
}

JSON example response:

{
   "success" : "1",
   "results" : {
      "eventID" : "548832",
      "routeplanID" : "2434"
   }
}

Example 2

Create a route plan to try for 20 seconds to deliver the call via SIP to 923@sip.mycompany.com or phone number 01234567890 if unsuccessful:

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
    "func" : "telecoms.routeplan.create",
    "args" : {
       "items" : [
          {
             "dur" : 20,
             "type" : "sip",
             "arg" : {
                "ext" : "923",
                "host" : "sip.mycompany.com"
             }
          },
          {
             "type" : "number",
             "arg" : "01234567890",
             "dur" : 0
          }
       ],
       "desc" : "sip routeplan"
    }
}

JSON example response:

{
   "results" : {
      "eventID" : "548833",
      "routeplanID" : "2435"
   },
   "success" : "1"
}

Example 3

Create a route plan to play an announcement with soundclipID 9283 (see the telecoms.soundclip functions), then dial three numbers all at the same time. Try two of them for 25 seconds but limit one of them to 15 seconds eg to avoid a remote voicemail answering.

If none answer, send the caller to voicemail.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
    "func" : "telecoms.routeplan.create",
    "mode" : "parallel",
    "args" : {
       "items" : [
          {
             "type" : "announcement",
             "arg" : 9283,
          },
          {
             "type" : "number",
             "arg" : "01234567890",
             "dur" : 25
          },
          {
             "type" : "number",
             "arg" : "02345678901",
             "dur" : 25
          },
          {
             "type" : "number",
             "arg" : "03456789012",
             "dur" : 15
          },
          {
             "type" : "voicemail",
             "arg" : 2822,
          }
       ],
       "desc" : "Support line"
    }
}

JSON example response:

{
   "results" : {
      "eventID" : "549232",
      "routeplanID" : "2436"
   },
   "success" : "1"
}