The IVR Menu documentation page.
You may also want to reference this;
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.
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.
To intercept only if the call is not bridged (available since git-58fe45a):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:
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.
- When using a "phrase:my_phrase" you can specify the string to pass along for input pattern matching like so: "phrase:my_phrase:options|option2".
- 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-macro -
- confirm-key - the key that tells the IVR that digit-entry is finished. Defaults to #, even if blank.
To override the # as a built-in terminator and change it to * enter in the dialplan before you run the ivr this would disable.
max-failures - maximum wrong digits entry(ies) before ending the menu (default 3 if not specified or invalid (less than 1) values are Specified).
max-timeouts - maximum timeout retry(ies) before ending the menu (default will use the max_failures value or 3 if both are left blank Or invalid (less than 1) values are specified).
exec-on-max-failures - Execute a FreeSWITCH dialplan application on maximum failures
exec-on-max-timeouts - Execute a FreeSWITCH dialplan application on maximum timeouts
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).
digit-len - maximum number of digits to collect before searching for a matching menu entry.
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.
- menu-back - Return to the calling menu level.
menu-top - Return to the top level menu.
menu-exec-api was previously documented on this page and is documented in the FreeSWITCH book - it is however not currently supported.
Playing remote audio files
There are two ways to play remote audio:
Generally speaking, mod_http_cache is the preferred method, and this is explained below.
Here is an example using mod_http_cache:
By using the above, you can avoid hitting the remote server every time the audio needs to be played.
However, it introduces some issues that you need to be aware of:
- A suitable caching period needs to be used. If it's too high, then changes to the audio file won't happen in a timely fashion. Too low, and you risk having the same problems explained in mod_shout.
- The initial caching of the audio file directly impacts the IVR. If it takes 2 seconds for the audio file to cache initially, then the IVR will 'freeze' for 2 seconds. You can potentially look at using http_prefetch to get around this.
You will notice that audio files will start playing much quicker than mod_shout, and the first few milliseconds of audio might get cut off. To get around this, just introduce a 500ms sleep, like so:
Here is an example of using mod_shout:
However, you should be aware of the following problems;
- Every time an audio file needs to be played, a new HTTP request is made to the remote server. This could result in accidental DDoS.
- Any latency/slowness on the HTTP request will directly impact your IVR (if it takes 2 seconds to download the audio file, the IVR will 'freeze' for 2 seconds).
- There is noticeable delay between play events, even if your remote HTTP server is on the same machine!
- For the above reasons, this is not an advisable approach for production systems.
How to route the call if no DTMF is pressed
First, define the IVR main menu like this:
And then in your dialplan, you need:
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.
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 ' ':
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:
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!
Path for Sound Files
Use an absolute path value for the greeting sounds. When you use a relative path (i.e. you don't start with a forward slash) then it will assume that you want to use a sound file somewhere in the sounds directory structure.
Custom IVR Menu events since FreeSWITCH 1.6 .