If defined, this sound clip is played to the caller when they arrive at the menu. This sound clip is not interruptable by the caller, ie the caller must listen to the entire sound clip before they can make any menu selections. Any keypresses they make while this sound clip is playing are ignored.

If this argument is defined as well as prompt_bg_soundclipID, both sound clips are played but this one is played first.

If defined, this sound clip is played to the caller when they arrive at the menu. This sound clip can be interrupted by the caller, ie the caller has called you previously and already knows which option they want, they can make their selection without having to listen to the entire message play first.

If this argument is defined as well as prompt_fg_soundclipID, both sound clips are played but this one is played second. In this instance, the user must listen to the first sound clip in its entirity (because it is uninterruptable), but they may interrupt the second one (this one) by making a selection. This might be useful if you have to play a disclaimer that your callers must hear in full (prompt_fg_soundclipID) before presenting them with the menu options which they may choose to interrupt (prompt_bg_soundclipID).

If defined, this sound clip is played to the caller in acknowledgement of them choosing a valid menu option prior to routing the call to the destination defined by that option. This sound clip is not interruptable so you should keep it short, eg something like "thank you".

This sound clip would be played to the caller regardless of which (valid) option they chose.

If defined, this sound clip is played to the caller if they enter a non-valid option. It is uninterruptable. The caller must listen to the enture sound clip. Any further keypresses they make during its playback will be ignored.

If both this (badchoice_fg_soundclipID) and badchoice_bg_soundclipID are defined, both are played but this one is played first.

If defined, this sound clip is played to the caller if they enter a non-valid option. It is interruptable, so they can immediately follow up by keying a valid option while this sound clip is playing.

If both badchoice_fg_soundclipID and this (badchoice_bg_soundclipID) are defined, both sound clips are played but this one is played second. In this instance, the user must listen to the first sound clip in its entirity (because it is uninterruptable), but they may interrupt the second one (this one) by making a new selection.

If defined, this sound clip is played to the caller after 'timeout_response' seconds (see the timeout_response argument) if they fail to enter any options (whether valid or not) in that time. This might happen if someone is calling from an old fashioned phone that does not have a DTMF (tone dial) keypad, eg one of the old rotary dial telephones.

If defined, this sound clip is played to the caller if/when:

• the caller fails to make a selection (valid or not) within timeout_response seconds
• the menu is repeated (as a result of the number of menu repeats being less than the max value defined in nochoice_maxreplays)
• the caller again fails to make a selection
• the above cycle repeats until the menu has been repeated nochoice_maxreplays times
• the caller still fails to make a selection

In the above circumstances, the system will hang up the call but just before doing this, it will play this sound clip to the caller. If this sound clip is not defined, the system will just hang up the call without playing a message.

This setting only comes into effect if some of the defined menu options have a different number of digits than some of the others.

If all menu options have the same number of digits (in most cases, menu options will be a single digit, eg "press 1 for sales, press 2 for support or press 0 to hear these options again"), then the system will action the caller's selection as soon as they have entered the requisite number of digits.

If, however, some options have more digits (eg "press 1 for sales, 2 for support or press 100 for accounts)", if the caller presses 1, the system doesn't know whether they want option 1 or may be in the middle of entering "100". In these cases, as soon as the caller has started pressing digits, it will wait for a period of time before assuming that they have finished typing. The length of time it waits, in seconds, is defined in the timeout_digit argument.

If, in the above example, the caller enters "100", the system knows that there are no options with more than 3 digits so it will act immediately on their selection.

If an impatient caller wants to choose one of the shorter options, instead of them having to wait for timeout_digit seconds before their selection is actioned, they may press "#" to indicate that they have finished entering digits.

If this argument is not supplied, the system will assume a default setting of 3 seconds.

This is the number of seconds that the system will wait for a caller to begin entering their selection.

If the caller fails to enter anything after this time ...

• if nochoice_fg_soundclipID is defined, the system will play that sound clip to the caller
• if nochoice_maxreplays is set and the menu has not yet been repeated this many times, the IVR will be replayed to the caller (ie it will return the call to the start of the menu, ie replay the initial prompt sound clips and wait again for the caller's selection), else ...
• if default_choice is defined, the system will assume that the seletion the user made was the one that corresponds to the default_choice digits. The call will then proceed as if the caller actually entered these digits, else ...
• if default_choice is NOT defined, the system will hang up the call

If this argument is not supplied, the system will assume a default setting of 10 seconds.

If this is defined, the system will assume that the seletion the user made was the one that corresponds to the default_choice digits. The call will then proceed as if the caller actually entered these digits.

Set this to the number of times you want the IVR menu to be repeated if the user does not make a selection. If the user has not made a selection after the max number of replays has been reached, then

• if default_choice is set, the system will assume that the user has made this selection and route the call as if they had actually selected this option
• if default_choice is not set, the system will hang up the call

This argument is where you define the options that the caller can enter, and what happens when they choose one.

The argument takes a list of option records (list/array/whatever, depending on what it's called in your chosen programming language). Each option record consists of these elements:

• keypress (mandatory) - a string of digits (min 1 digit, max 10 digits) corresponding to what the caller should press to select this option
• routeto_type (mandatory) - the type of thingy the call should route to if the caller selects this option. Valid options are:
  • number - route the call to a destination phone number; supply the number in the destnumber element
  • routeplan - route the call to a routeplan; supply the corresponding routeplan's ID in the routeplanID element. You can create route plans with the telecoms.routeplan.create function.
  • dayparting - route the call to a day parting; supply the corresponding day parting's ID in the daypartID element. You can create day partings with the telecoms.dayparting.create function.
  • sip - route the call via SIP to a SIP gateway; supply the SIP address in the destargs element
  • voicemail - route the call directly to voicemail; supply the ID of the voicemail mailbox in the mailboxID element. You can create voicemail mailboxes with the telecoms.voicemail.mailbox.create function.
  • ivr - route the call to another IVR menu (eg a sub menu, or back to the main menu); supply the IVR menu's ID in the ivrID element. If you specify an ivrID of 0 then the call will be routed back to this menu (handy if you want the caller to be able to choose an option to hear this menu again).
  • hangup - hangs up the call. For a better user experience, it would be best to also define fg_soundclipID with any options that have routeto_type set to hangup so that the user is played a message prior to being disconnected.
• desc (optional) - a brief textual description of this option (max 50 characters)
• fg_soundclipID (optional) - if defined, the ID of the sound clip to play to the caller if they select this option. This allows you to play a different acknowledgement sound to the caller depending on what option they choose, prior to proceeding the call. Note: if this is defined as well as the global goodchoice_fg_soundclipID argument, both soundclips are played. In this instance, the one defined in goodchoice_fg_soundclipID is played first, followed by the one defined in this option's fg_soundclipID element.
• callee_whisper_soundclipID (optional) - if defined, this soundclip is played to the called party (as a called party whisper/announcement) when the call is connected. This might be useful if you have several menu options routing to the same destination and you want the person answering the call to know which option was selected prior to being connected to the caller.

The following elements are mutually exclusive. Whichever you supply depends on what value you defined in the routeto_type element:

• destnumber (if routeto_type=number) - the destination phone number to route the call to
• routeplanID (if routeto_type=routeplan) - the ID of the route plan to route the call to
• daypartID (if routeto_type=dayparting) - the ID of the day parting to route the call to
• destargs (if routeto_type=sip) - the SIP address to where to route the call over SIP
• mailboxID (if routeto_type=voicemail) - the mailboxID of the voicemail mailbox
• ivrID (if routeto_type=ivr) - the ID of the IVR menu to route this call to (supply 0 to refer back to this menu)

The IVR system has 3 main modes of operation:

• normal - this is the default value and is what you would want most of the time. The IVR menu acts like a normal menu with prompts and pre-defined choices for the caller to select.
• cgi_simple - use the IVR menu purely as a data gathering tool. The user's keypresses are logged with the call data but do not influence call routing. See below for more detail. This argument also needs the following arguments to be specified:
  • cgi_maxdigits
  • cgi_simple_goodchoice_opt
• cgi_full - integration with a script on your web site. When a caller arrives at the IVR menu, the IVR system makes an HTTP or HTTPS connection to a script on your web site for call routing instructions. See below for more detail. This argument also needs the following arguments to be specified:
  • cgi_maxdigits
  • cgi_simple_goodchoice_opt

With the CGI modes, you still need to define an option in the options argument that defines each destination the call could route to. The difference is that the system then routes the call through to the option whose keypress value matches the value in the cgi_simple_goodchoice_opt argument (if in cgi_simple mode) or as specifed in the response to a remote script from your web site (in cgi_full mode).

With cgi_full mode, It's perhaps easiest to think of the remote script telling the IVR system to "route the call as if the user pressed '3'" (for example). An option for keypress '3' still needs to be defined; it's just that the user won't specifically enter that themselves.

mode "cgi_simple"

In this mode, the IVR menu acts mainly as a data gathering exercise. User input doesn't play any part in call routing, but the digits entered by the user are stored within the call data records (CDRs) in an IVRTRACE parameter within the "extra_params" field. This field is not normally returned by default so you have to request it with the telecoms.calldata.detail.get:optfields argument.

cgi_simple IVR menus can be used as end of call IVR menus, which allows the operator to key in some data about the call for later analysis once the caller has hung up.

mode "cgi_full"

This allows an IVR menu to be integrated with a script on your web site to allow a script on your web site to make call routing decisions in real time depending on user input.

This can be useful, for example, if you wanted to route premium customers to a different department. In this example, you might set up the IVR menu to prompt the user for an account number. Our system will then make an HTTP connection to a script on your site with details about the call, including the digits the caller entered. Your system could then check what they entered against information in your database and then in the response instruct the IVR system which of the pre-defined options to route the call to. If the user entered a valid account number, you may choose to route them to a sub-menu that prompts them to enter a PIN. This sub-menu would also connect to a script on your web site in order to verify the PIN is the correct one for that account. The IVR system can then be instructed to route them through to the appropriate department, or redirect them back to the main menu, or whatever.

This parameter is required when the IVR menu is operating in cgi_simple mode. It tells the IVR system the maximum number of digits to accept from the user. See the description of the mode argument for more information on cgi_simple mode.

This parmeter is required when the IVR menu is operating in cgi_simple mode.

When you define a cgi_simple IVR, you need to specify one option in the options parameter with a keypress value. This parameter should contain the digits that match that keypress option so that the system knows where to route the call once the user has entered digits. See the description of the mode argument for more information on cgi_simple mode.

See the example given in telecoms.ivr.create:cgi_full_response_url for an example of how this parameter is used.

Specifies whether calls to the script defined in cgi_full_init_url parameter should use the HTTP GET or HTTP POST method. If unspecified, the system defaults to using HTTP GET.

In cgi_full mode, the IVR system queries a remote script at the URL given in this parameter to find out where to route the call. This is probably easier to explain by example. You might set up the following IVR menu on a tech support line so that you can divert premium customers to your premium tech suopport department and everybody else to the basic level tech support department:

• Set up the menu that has 3 destinations defined in options:
  • keypress "1" routes the call to the number of your basic level tech support department
  • keypress "2" routes the call to the number of your premium level tech support department
  • keypress "99" routes the call to the number you want to send callers to if your web site is down. If this is the case, the system will be unable to determine the status of the caller's account, so it will route the call to the destination defined in this option instead.
• specify the mode parameter with the value "cgi_full"
• specify the cgi_full_init_url parameter with the value "http://www.example.com/customer_validate_init.php"
• specify the cgi_full_response_url parameter with the value "http://www.example.com/customer_validate.php"
• specify the cgi_full_failchoice parameter with the value "99"

You then use telecoms.num.route to route a phone number at this IVR menu, using the ivrID that telecoms.ivr.create returned to you.

A call comes in and arrives at the IVR menu. The following (example) happens:

• The IVR system makes an HTTP GET call to http://www.example.com/customer_validate_init.php with the following parameters:
  • menuaction=init
  • uniqueID=(a unique identifier string for this phone call)
  • dni=(the phone number the caller dialled)
  • ivrID=(the ivrID of this IVR menu)
  • tstamp=(the unix timestamp representing the time the user arrived at the menu)
• The remote script responds with a plain text reply consisting of the text "cgi_maxdigits=8" (without the quotes). This tells the IVR system to accept a maximum of 8 digits from the user.
• the system plays the audio prompt to the user, inviting them to enter their account number
• the user keys in the digits of their account number, in this exammple they enter "92378237"
• the system makes an HTTP GET request to http://www.example.com/customer_validate.php, supplying the following parameters:
  • menuaction=response
  • uniqueID=(the unique identifier string for this phone call - this is the same one that was supplied earlier)
  • dni=(the phone number the caller dialled)
  • ivrID=(the ivrID of this IVR menu)
  • tstamp=(the unix timestamp representing the time the user arrived at the menu)
  • userchoice=92378237 (these are the digits the user entered)
  • opts=1,2,99 (this is a comma separated list of the defined keypress options)
• the remote script checks its database and determines that account 92378237 is a premium account, so sends the text response "keypress=2" (without the quotes). This tells the IVR system to route the caller through to the option that is marked as having keypress "2", which routes through to the premium support number.
• the system dials the premium support number defined in the option for keypress 2 and connects the call

In a live system you would probably want to perform other validation steps, eg asking a caller to enter their PIN after they've entered their account number. To do that, you would create an additional cgi_full IVR menu that prompts them for their PIN and calls your remote script with the digits they entered. Amongst the parameters that are sent will be the same uniqueID value so you will be able to correlate the various calls to your remote script with the same call (the uniqueID value is unique to a phone call, but is repeated with any script called from within that phone call). You would amend your main menu so that the option defined with keypress 2 would route to the second IVR menu, not directly to your support department's phone number.

With several steps of data entry, your script can build up a database record of information provided by the customer and take appropriate action.

Specifies whether calls to the script defined in cgi_full_response_url parameter should use the HTTP GET or HTTP POST method. If unspecified, the system defaults to using HTTP GET.

See the example given in telecoms.ivr.create:cgi_full_response_url for an example of how this parameter is used.