IVR Menu

From FreeSWITCH Wiki

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 freeswitch.xml file ivr.conf configuration as below..

<configuration name="ivr.conf" description="IVR menus">
  <menus>
    <!-- demo IVR setup -->
    <!-- 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"
	  digit-len="4">
      <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 -->
    </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">
      <entry action="menu-top" digits="*"/>
     </menu>
  </menus>
</configuration>


<!-- TTS sample; non-functional but it demonstrates say: and TTS -->
<!--
    <menu name="demo3"
          greet-long="say:Press 1 to join the conference, Press 2 to join the other conference"
          greet-short="say:Press 1 to join the conference, Press 2 to join the other conference"
          invalid-sound="say:invalid extension"
          exit-sound="say:exit sound"
          timeout ="15000"
          max-failures="3">
      <entry action="menu-exit" digits="*"/>
      <entry action="menu-playback" digits="1" param="say:You pressed 1"/>
      <entry action="menu-call-transfer" digits="2" param="1000"/>
      <entry action="menu-call-transfer" digits="3" param="1001"/>
    </menu>
-->

The IVR Menu also supports prompts using a TTS engine or the phrase macro. To speak a text prompt using TTS preface the prompt with "say:". 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"
        greet-long="phrase:mainmenu_phrase_macro"
        greet-short="say:main menu"
        invalid-sound="say:invalid entry"
        exit-sound="say:goodbye"
        timeout ="10000"
        max-failures="3"
        tts-engine="cepstral"
        tts-voice="david"
        phrase_lang="en">
           <entry action="menu-exit" digits="*"/>
           <entry action="menu-sub" digits="2" param="menu2"/>
           <entry action="menu-exec-api" digits="3" param="api arg"/>
           <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"/>
     </menu>

Usage:

ivr <menu_name>

Examples:

<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.
• timeout - number of mili-seconds to wait for a selection
• 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.

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-api - Execute a FreeSWITCH API
• menu-exec-app - Execute a FreeSWITCH dialplan application
• menu-play-sound - Play a sound file
• menu-say-text - Speak a TTS prompt
• menu-say-phrase - Say a Phrase Macro
• 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"