IVR engine overview

Unlike many applications within FreeSWITCH which are built as modules, IVR is considered the core functionality of FreeSWITCH. It is used anytime a prompt is played and digits are collected. Even if you are not using the IVR application itself from your Dialplan, you will see IVR-related functions being utilized from various other applications. As an example, the voicemail application makes heavy use of IVR functionality when playing messages, while awaiting digits to control deleting, saving, and otherwise managing voicemails.

In this section, we will only be reviewing the IVR functionality that is exposed from within the ivr Dialplan application. This functionality is typically used to build an auto-attendant menu, although other functions are possible as well.

IVR XML configuration file

FreeSWITCH ships with a sample IVR menu are typically invoked by dialing 5000 from the sample Dialplan. When you dial 500, you will hear a greeting welcoming you to FreeSWITCH, and presenting your menu options. The menu options consist of calling the FreeSWITCH conference, calling the echo extension, hearing music on hold, going to a sub menu, or listening to screaming monkeys. We will start off reviewing the XML that powers this example.

Open conf/autoload_configs/ivr.xml which contains the following XML:

<configuration name=”ivr.conf” description=”IVR menus”>
<menus>
<!– demo IVR, Main Menu –>
<menu name=”demo_ivr”
greet-long=”phrase:demo_ivr_main_menu”
greet-short=”phrase:demo_ivr_main_menu_short”
invalid-sound=”ivr/ivr-that_was_an_invalid_entry.wav”
exit-sound=”voicemail/vm-goodbye.wav”
timeout=”10000″
inter-digit-timeout=”2000″
max-failures=”3″
max-timeouts=”3″
digit-len=”4″>
<entry action=”menu-exec-app” digits=”1″ param=”bridge
sofia/$${domain}/[email protected]”/>
<entry action=”menu-exec-app” digits=”2″ param=”transfer 9196
XML default”/>
<entry action=”menu-exec-app” digits=”3″ param=”transfer 9664
XML default”/>
<entry action=”menu-exec-app” digits=”4″ param=”transfer 9191
XML default”/>
<entry action=”menu-exec-app” digits=”5″ param=”transfer
1234*256 enum”/>
<entry action=”menu-exec-app” digits=”/^(10[01][0-9])$/”
param=”transfer $1 XML features”/>
<entry action=”menu-sub” digits=”6″ param=”demo_ivr_submenu”/>
<entry action=”menu-top” digits=”9″/>
</menu>

<!– Demo IVR, Sub Menu –>
<menu name=”demo_ivr_submenu”
greet-long=”phrase:demo_ivr_sub_menu”
greet-short=”phrase:demo_ivr_sub_menu_short”
invalid-sound=”ivr/ivr-that_was_an_invalid_entry.wav”
exit-sound=”voicemail/vm-goodbye.wav”
timeout=”15000″
max-failures=”3″
max-timeouts=”3″>
<entry action=”menu-top” digits=”*”/>
</menu>

</menus>
</configuration>

In the preceding example, there are two IVR menus defined. Let’s break apart the first one and examine it, starting with the IVR menu definition itself.

IVR menu definitions

The following XML defines an IVR menu named “demo_ivr”.

<menu name=”demo_ivr”
greet-long=”phrase:demo_ivr_main_menu”
greet-short=”phrase:demo_ivr_main_menu_short”
invalid-sound=”ivr/ivr-that_was_an_invalid_entry.wav”
exit-sound=”voicemail/vm-goodbye.wav”
timeout=”10000″
inter-digit-timeout=”2000″
max-failures=”3″
max-timeouts=”3″
digit-len=”4″>

We’ll use this menu’s name later when we route calls to the IVR from the Dialplan. Following the name, various XML attributes specify how the IVR will behave. The following options are available when defining an IVR’s options:

greet-long

The greet-long attribute specifies the initial greeting that is played when a caller reaches the IVR. This is different from the greet-short sound file which allows for introductions to be played, such as “Thank you for calling XYZ Company”. In the sample IVR, the greet-long attribute is a Phrase Macro that plays an introductory message to the caller (“Welcome to FreeSWITCH…”) followed by the menu options the caller may choose from.

Argument syntax: Sound file name (or path + name), TTS, or Phrase Macro

Examples:

greet-long=”my_greeting”
greet-long=”phrase:my_greeting_phrase”
greet-long=”say:Welcome to our company. Press 1 for sales, 2 for
support.”

greet-short

The greet-short attribute specifies the greeting that is re-played if the caller enters invalid information, or no information at all. This is typically the same sound file as greet-long without the introduction. In the sample IVR, the greet-short attribute is a Phrase Macro that simply plays the menu options to the caller, and does not play the lengthy introduction found in greet-long.

Argument syntax: Sound file name (or path + name), TTS, or Phrase Macro

Examples:

greet-short=”my_greeting_retry”
greet-long=”phrase:my_greeting_retry_phrase”
greet-long=”say:Press 1 for sales, 2 for support.”

invalid-sound

The invalid-sound attribute specifies the sound that is played when a caller makes an invalid entry.

Argument syntax: Sound file name (or path + name), TTS, or Phrase Macro

Examples

invalid-sound=”invalid_entry.wav”
invalid-sound=”phrase:my_invalid_entry_phrase”
invalid-sound=”say:That was not a valid entry”

exit-sound

The exit-sound attribute specifies the sound, which is played when a caller makes too many invalid entries or too many timeouts occur. This file is played before disconnecting the caller.

Argument syntax: Any number, in milliseconds

Examples:

exit-sound=”too_many_bad_entries.wav”
exit-sound=”phrase:my_too_many_bad_entries_phrase”
exit-sound=”say:Hasta la vista, baby.”

timeout

The timeout attribute specifies the maximum amount of time to wait for the user to begin entering digits after the greeting has played. If this time limit is exceeded, the menu is repeated until the value in the max-timeouts attribute has been reached.

Argument syntax: Any number, in milliseconds

Examples:

timeout=”10000″
timeout=”20000″

inter-digit-timeout

The inter-digit-timeout attribute specifies the maximum amount of time to wait in-between each digit the caller presses. This is different from the overall timeout.It is useful to allow enough time to enter as many digits as necessary, without frustrating the caller by pausing too long after they are done making their entry. For example, if both 1000 and 1 are valid IVR entries, the system will continue waiting for the inter-digit-timeout length of time after 1 is entered, before determining that it is the final entry.

Argument syntax: Any number, in milliseconds

Examples:

inter-digit-timeout=”2000″

max-failures

The max-failures attribute specifies how many failures, due to invalid entries, to tolerate before disconnecting.

Argument syntax: Any number

Examples:

xx-xx=”too_many_bad_entries.wav”
xx-xx=”phrase:my_too_many_bad_entries_phrase”

max-timeouts

The max-timeouts attribute specifes how many timeouts to tolerate before disconnecting.

Argument syntax: Any number

Examples:

max-timeouts=”3″

digit-len

The digit-len attribute specifes the maximum number of digits that the user can enter before determining the entry is complete.

Argument syntax: Any number greater than 1.

Examples:

digit-len=”4″

tts-voice

The tts-voice attribute specifes the specifc text-to-speech voice that should be used.

Argument syntax: Any valid text-to-speech engine.

Examples:

tts-voice=”Mary”

tts-engine

The tts-engine attribute specifies the specific text-to-speech engine that should be used.

Argument syntax: Any valid text-to-speech engine.

Examples:

tts-engine=”flite”

confirm-key

The confirm-key attribute specifes the key which the user can press to signify that they are done entering information.

Argument syntax: Any valid DTMF digit.

Examples:

confirm-key=”#”

These attributes dictate the general behavior of the IVR.

IVR menu destinations

After defining the global attributes of the IVR, you need to specify what specific destinations (or options) are available for the caller to press. You do this with <entry > XML elements. Let’s review the first five XML options used by this IVR:

<entry action=”menu-exec-app” digits=”1″ param=”bridge
sofia/$${domain}/[email protected]”/>
<entry action=”menu-exec-app” digits=”2″ param=”transfer 9196 XML
default”/>
<entry action=”menu-exec-app” digits=”3″ param=”transfer 9664 XML
default”/>
<entry action=”menu-exec-app” digits=”4″ param=”transfer 9191 XML
default”/>
<entry action=”menu-exec-app” digits=”5″ param=”transfer 1234*256
enum”/>
<entry action=”menu-exec-app” digits=”/^(10[01][0-9])$/”
param=”transfer $1 XML features”/>

Each preceding entry defines three parameters—an action to be taken, the digits the caller must press to activate that action, and the parameters that are passed to the action. In most cases you will probably use the menu-exec-app action, which simply allows you to specify an action and parameters to call just as you would from the regular Dialplan (bridge, transfer, hangup, and so on.). These options are all pretty simple—they define a single digit which, when pressed, either bridges a call or transfers the call to an extension.

There is one entry that is a bit different from the rest, which is the fnal IVR entry. It deserves a closer look.

 

<entry action=”menu-exec-app” digits=”/^(10[01][0-9])$/”
param=”transfer $1 XML features”/>

This entry definition specifes a regular expression for the digits feld. This regular expression feld is identical to the expressions you would use in the Dialplan. In this example, the IVR is looking for any four-digit extension number from 1000 through 1019 (which is the default extension number range for the predefined users in the directory). As the regular expression is wrapped in parenthesis, the result of the entry will be passed to the transfer application as the $1 channel variable. This effectively allows the IVR to accept 1000-1019 as entries, and transfer the caller directly to those extensions when they are entered into the IVR.

The remaining IVR entry actions are a bit different. They introduce menu-sub as an action, which transfers the caller to an IVR sub-menu, and menu-top, which restarts the current IVR and replays the menu.

<entry action=”menu-sub” digits=”6″ param=”demo_ivr_submenu”/>
<entry action=”menu-top” digits=”9″/>

Several other actions exist that can be used within an IVR. The complete list of actions you can use from within the IVR include the following:

menu-exec-app

The menu-exec-app action, combined with a param field, executes the specified application and passes the parameterslisted to that application. This is equivalent to using <action application=”app” data=”data”> in your Dialplan. The most common use of menu-exec-app is to transfer a caller to another extension in the Dialplan.

Argument syntax: application <params>

Examples:

<entry digits=”1″ action=”menu-exec-app” param=”application param1
param2 param3 …”>
<entry digits=”2″ action=”menu-exec-app” param=”transfer 9664 XML
default”>

menu-exec-api

The menu-exec-api action, combined with a param feld, executes the specifed API command and passes the parameters listed to that command. This is equivalent to entering API commands at the CLI or from the event socket.

Argument syntax: api_command <params>

Examples:

<entry digits=”1″ action=”menu-exec-api” param=”eval Caller Pressed
1!”>

menu-play-sound

The menu-play-sound action, combined with a param field, plays a specified sound file.

Argument syntax: valid sound file

<entry digits=”1″ action=”menu-play-sound”
param=”screaming_monkeys.wav”>

menu-back

The menu-back action returns to the previous IVR menu, if any.

Argument syntax: none

Examples:

<entry digits=”1″ action=”menu-back”>

menu-top

The menu-top action restarts this IVR’s menu.

Argument syntax: None.

Examples:

<entry digits=”1″ action=”menu-top”>

Take a look at the XML for the sample sub-menu IVR and see if you can fgure out what it does. Also note how it is called above, when clicking 6 from the main menu.

<menu name=”demo_ivr_submenu”
greet-long=”phrase:demo_ivr_sub_menu”
greet-short=”phrase:demo_ivr_sub_menu_short”
invalid-sound=”ivr/ivr-that_was_an_invalid_entry.wav”
exit-sound=”voicemail/vm-goodbye.wav”
timeout=”15000″
max-failures=”3″
max-timeouts=”3″>
<entry action=”menu-top” digits=”*”/>
</menu>