Edit an existing IVR menu.

You can use this function to edit any aspect of an IVR menu and its options.

See telecoms.ivr.create for a fuller explanation of how IVR menus work.

Of the optional arguments below, you only need to supply arguments that correspond with values that you are changing. Any arguments you omit will cause that setting in the IVR menu to remain unchanged.

Arguments:

Example 1

You already have a basic IVR menu that

• has an ivrID of 4
• has a description of "Main menu"
• plays soundclip 1 to callers when they arrive at the menu
• has the following options defined:
• pressing "1" routes the caller to the sales department on 02031001000
• pressing "2" routes the caller to the service department on 02031002000

Your IVR menu might look like this:

{
  'ivrID' => '4',
  'desc' => 'Main menu',
  'prompt_bg_soundclipID' => '1',
  'nochoice_maxreplays' => '3',
  'timeout_response' => '10',
  'timeout_digit' => '3',
  'options' =>
    [
      {
        'keypress' => '1'
        'routeto_type' => 'number',
        'destnumber' => '02031001000',
      },
      {
        'keypress' => '2'
        'routeto_type' => 'number',
        'destnumber' => '02031002000',
      }
    ],
}

You now decide that callers who enter a non-valid option (ie press something that is not defined as an option) should hear a message telling them. This message is in soundclip 84 which you've recently uploaded with telecoms.soundclip.create and assigned it the "ivr.prompt" role.

You also want to add descriptions to the options.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
    "func" : "telecoms.ivr.edit",
    "args" : {
       "badchoice_bg_soundclipID" : 84,
       "options.edit" : [
          {
             "keypress" : "1",
             "desc" : "sales"
          },
          {
             "desc" : "service",
             "keypress" : "2"
          }
       ],
       "ivrID" : 4
    }
}

The response

JSON example response:

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

Now your IVR menu looks like below. Note that it now shows badchoice_bg_soundclipID in the main record, plus the options records are now showing descriptions:

{
  'ivrID' => '4',
  'desc' => 'Main menu',
  'prompt_bg_soundclipID' => '1',
  'badchoice_bg_soundclipID' => '84',
  'nochoice_maxreplays' => '3',
  'timeout_response' => '10',
  'timeout_digit' => '3',
  'options' =>
    [
      {
        'keypress' => '1'
        'desc' => 'sales',
        'routeto_type' => 'number',
        'destnumber' => '02031001000',
      },
      {
        'keypress' => '2'
        'desc' => 'service',
        'routeto_type' => 'number',
        'destnumber' => '02031002000',
      }
   ],
}

Example 2

You've decided to further modify the menu you had from the above example such that if a caller does not select an option from the menu, they get transferred to the main switchboard. In preparation for this, you've recorded a new sound file to play to the callers when they arrive at the menu which ends with the message "or please hold to speak to the switchboard". Once you have edited your menu, you will need to rememeber to upload this in place of the existing sound file with telecoms.soundclip.edit so that the callers are aware of the new options.

You also decide to add an additional menu option, "3", to transfer to the accounts department (and remembered to mention that in your new recording). Because the accounts department is only open in the mornings, you have used telecoms.dayparting.create to create a day parting that routes to their number during the hours that are there but routes to voicemail at all other times. In this example, this day parting has a daypartID of 604.

In order to provide the default action, you need to define it as an option so that it has a defined keypress (it doesn't matter if you don't tell the caller what this is) and then you set this as the default_choice.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
    "func" : "telecoms.ivr.edit",
    "args" : {
       "default_choice" : "9",
       "ivrID" : 4,
       "options.add" : [
          {
             "routeto_type" : "dayparting",
             "keypress" : "3",
             "desc" : "accounts",
             "daypartID" : 604
          },
          {
             "routeto_type" : "number",
             "destnumber" : "02031009999",
             "keypress" : "9",
             "desc" : "main switchboard"
          }
       ]
    }
}

The response

JSON example response:

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

Now your IVR menu looks like below. Note that it now shows default_choice in the main record, plus the options records how have the two new options:

{
  'ivrID' => '4',
  'desc' => 'Main menu',
  'prompt_bg_soundclipID' => '1',
  'badchoice_bg_soundclipID' => '84',
  'default_choice' => '9',
  'nochoice_maxreplays' => '3',
  'timeout_response' => '10',
  'timeout_digit' => '3'
  'options' => [
              {
                'keypress' => '1'
                'desc' => 'sales',
                'routeto_type' => 'number',
                'destnumber' => '02031001000',
              },
              {
                'keypress' => '2'
                'desc' => 'service',
                'routeto_type' => 'number',
                'destnumber' => '02031002000',
              },
              {
                'keypress' => '3'
                'desc' => 'accounts',
                'routeto_type' => 'dayparting',
                'daypartID' => '604',
              },
              {
                'keypress' => '9'
                'desc' => 'main switchboard',
                'routeto_type' => 'number',
                'destnumber' => '02031009999',
              }
            ],
}

Example 3

You now decided to make the following changes to your IVR menu:

• add an option for the caller to press "0" to hear the menu options again
• add an option "4" to present the caller with a sub-menu
• add a message played to the caller when they choose option "1"

Let's assume that you have used telecoms.ivr.create to create an additional IVR menu for the sub-menu for option "4" and that this has an ivrID of 5.

Let's also assume that the sound file you have uploaded using telecoms.soundclip.create for playback to the caller in response to them choosing option "1" has a soundclipID of 2.

In order to add the option to repeat the menu, you will need to define an option that routes back to this same IVR menu. You do this by supplying routeto_type of "ivr" and specifying ivrID of 4 (because this menu has an ivrID of 4) or you can specify an ivrID of 0 which is a special case to mean "this menu" and will be internally translated by the API to the correct ID.

JSON example request:

POST https://live.apicontrol.co.uk/1/json
{
    "auth" : {
        "username" : "YOURUSERNAME",
        "password" : "YOURPASSWORD",
    },
    "func" : "telecoms.ivr.edit",
    "args" : {
       "options.edit" : [
          {
             "keypress" : "1",
             "fg_soundclipID" : 2
          }
       ],
       "options.add" : [
          {
             "desc" : "repeat this menu",
             "keypress" : "0",
             "routeto_type" : "ivr",
             "ivrID" : 0
          },
          {
             "ivrID" : 5,
             "keypress" : "4",
             "routeto_type" : "ivr",
             "desc" : "sub menu"
          }
       ],
       "ivrID" : 4
    }
}

The response

JSON example response:

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

Now your IVR menu looks like below. Note that the API has translated your ivrID of 0 into its true ivrID:

{
  'ivrID' => '4',
  'desc' => 'Main menu',
  'prompt_bg_soundclipID' => '1',
  'badchoice_bg_soundclipID' => '84',
  'default_choice' => '9',
  'nochoice_maxreplays' => '3',
  'timeout_response' => '10',
  'timeout_digit' => '3'
  'options' => [
              {
                'keypress' => '0'
                'desc' => 'repeat this menu',
                'ivrID' => '4',
                'routeto_type' => 'ivr',
              },
              {
                'keypress' => '1'
                'desc' => 'sales',
                'fg_soundclipID' => '2',
                'routeto_type' => 'number',
                'destnumber' => '02031001000',
              },
              {
                'keypress' => '2'
                'desc' => 'service',
                'routeto_type' => 'number',
                'destnumber' => '02031002000',
              },
              {
                'keypress' => '3'
                'desc' => 'accounts',
                'routeto_type' => 'dayparting',
                'daypartID' => '604',
              },
              {
                'keypress' => '4'
                'desc' => 'sub menu',
                'routeto_type' => 'ivr',
                'ivrID' => '5',
              },
              {
                'keypress' => '9'
                'desc' => 'main switchboard',
                'routeto_type' => 'number',
                'destnumber' => '02031009999',
              }
            ],
}