IVR Menu

From FreeSWITCH Wiki
Revision as of 21:00, 31 March 2011 by Nikko (Talk | contribs)

Jump to: navigation, search


General Concept

The IVR Menu feature allows you to easily create IVR menus by describing them in XML. (See also phrase macros)

Menus are defined in the autoload_configs/ivr.conf.xml file configuration as below.

<configuration name="ivr.conf" description="IVR menus">
    <!-- demo IVR setup -->
    <!-- demo IVR, Main Menu -->
    <menu name="demo_ivr"
          timeout ="10000"
      <entry action="menu-exec-app" digits="1" param="bridge sofia/$${domain}/888@conference.freeswitch.org"/>
      <entry action="menu-exec-app" digits="2" param="transfer 9996 XML default"/>    <!-- FS echo -->
      <entry action="menu-exec-app" digits="3" param="transfer 9999 XML default"/>    <!-- MOH -->
      <entry action="menu-sub" digits="4" param="demo_ivr_submenu"/>  <!-- demo sub menu -->
      <entry action="menu-exec-app" digits="5" param="transfer 1234*256 enum"/>    <!-- Screaming monkeys -->
      <entry action="menu-exec-app" digits="/^(10[01][0-9])$/" param="transfer $1 XML default"/> <!-- dial ext & x-fer -->
      <entry action="menu-top" digits="9"/>    <!-- Repeat this menu -->
    <!-- Demo IVR, Sub Menu -->
    <menu name="demo_ivr_submenu"
      <entry action="menu-top" digits="*"/>

The IVR Menu supports prompts using the phrase macro. To speak a phrase macro preface your macro name with "phrase:". Be sure to specify the tts-engine, tts-voice, and phrase-lang parameters. See the following menu example.

     <menu name="main"
        timeout ="10000"
           <entry action="menu-exit" digits="*"/>
           <entry action="menu-sub" digits="2" param="menu2"/>
                       <entry action="menu-say-phrase" digits="4" param="enteraccount"/>
           <entry action="menu-back" digits="5"/>
           <entry action="menu-call-transfer" digits="7" param="888"/>
           <entry action="menu-sub" digits="8" param="menu8"/>


ivr <menu_name>


<action application="ivr" data="main"/>

Note it is sometime necessary to have the following before the call to the ivr application so it won't pick up in early media:

<action application="answer"/>


Menu tag options

  • name - the name of the ivr menu
  • greet-long - the menu prompt played the first time the menu is played. May be a filename (starting with \ or /) or "say:Text to speak" for TTS, or "phrase:phrase_macro_name" to speak a phrase macro.
  • greet-short - the shorter version of the menu prompt played when the menu loops. May be filename, say, or phrase.
  • invalid-sound - played when no entry or an invalid entry is made. May be filename, say, or phrase.
  • exit-sound - played when the menu is terminated, May be filename, say, or phrase.
  • inter-digit-timeout - number of milliseconds to wait for a selection
  • timeout - number of milliseconds to wait for a after playing confirm-macro to conform entered digits
  • confirm-key -
  • confirm-attempts -
  • max-failures - or max-retries before ending the menu
  • tts-engine - name of TTS engine to speak text (ie. cepstral). (optional)
  • tts-voice - name of TTS voice to use to speak text (ie. david). (Necessary if tts-engine is specified)
  • phrase_lang - optional override language to use. If specified will override the default_language channel variable setting.
  • digit-len -

NOTE: As of SVN Rev. 13006 the following tags expand channel variables: greet-long, greet-short, invalid-sound, exit-sound

Each menu can support a number of actions bound to a key as follows:

  • menu-exit - Exit the IVR menues
  • menu-sub - Load a sub-menu
  • menu-exec-app - Execute a FreeSWITCH dialplan application
  • menu-play-sound - Play a sound file or speak text
 <entry action="menu-play-sound" digits="3" param="say: You pressed 3"/>
 <entry action="menu-play-sound" digits="6" param="voicemail/vm-goodbye.wav"/>

* menu-say-phrase - Say a Phrase Macro Say phrase is now done by menu-exec-app with parameters of "phrase MACRONAME"

  • menu-back - Return to the calling menu level
  • menu-top - Return to the top level menu

* menu-call-transfer - Transfer to a dialplan extension - Transfer is now done by menu-exec-app with parameters of "transfer EXTENSION DIALPLAN CONTEXT"

  • menu-exec-api was previously documented on this page and is documented in the FreeSWITCH book - it is however not currently supported.


How to route the call if no DTMF is pressed

First, define the IVR main menu like this:

    <menu name="ivr-test"
      <entry action="menu-exec-app" digits="1" param="bridge sofia/internal/1001%"/>
      <entry action="menu-exec-app" digits="2" param="bridge sofia/internal/1002%"/>
      <entry action="menu-exec-app" digits="3" param="bridge sofia/internal/1003%"/>

and then in your dialplan, you need:

   <extension name="from_carrier_to_ivr-test">
      <condition field="destination_number" expression="^15559876543$">
	<action application="set" data="hangup_after_bridge=true"/>
        <action application="ivr" data="ivr-test"/>
        <action application="bridge" data="sofia/internal/1000%"/>

With this config, if the IVR manages to bridge the call, it will hang up when the bridge ends.

But if no DTMF is sent, twice in a row (max-timeouts control that), FreeSWITCH will exit the IVR menu and process the next dialplan line, which bridges to 1000.

How to run several apps with one digit

You need to use the execute_extension app, with the inline parameter.

For example:

  <menu name="ivr-test"
      <entry action="menu-exec-app" digits="1" param="execute_extension limit:'hash ivr in',
bridge:sofia/internal/1001%,playback:ivr/ivr-busy.wav,hangup inline"/>
      <entry action="menu-exec-app" digits="2" param="execute_extension limit:'hash ivr in',
bridge:sofia/internal/1002%,playback:ivr/ivr-busy.wav,hangup inline"/>

With execute_extension, you can add in sequence any apps you need, as in a regular XML extension, but the string containing the apps must not contain whitespaces.

So you need to replace them by \s, or as above, to put the substring with the spaces between ' ':

limit:'hash ivr in'

Also, see the playback and hangup apps after the bridge app.

In an IVR (to be confirmed formally), continue_on_fail=true is the default.

This means that if the bridge is not successful in my example, the file will be played back to the caller and the call will be hung up.

If you don't hang up the call there, the IVR will playback the greetings file again.

To end the call after a successful bridge, you just need to set:

<action application="set" data="hangup_after_bridge=true"/>

from the dialplan before calling the iVR, or in each execute_extension string, as in the previous example above.

Another way to run several apps with one digit

Simply list the same digit multiple times in the IVR menu definition. For instance if you have multiple entries for "1" then each entry for 1 will be executed in sequence if 1 is pressed. Note: if they are executed in reverse order you are using a version of Freeswitch that was built prior to September 2010 - to fix this you can either get a newer version or put the entries in reverse order so that they will be executed in the correct order!