Chapter 6. Using the Built-in XML IVR Engine

The built-in IVR (Interactive Voice Response) engine is a powerful component of the FreeSWITCH system. It allows messages to be played and interactive responses (usually touch-tones) to be processed, in order to direct calls to particular destinations. It can ultimately allow callers to hear information without needing to speak to a live person, select options that enable/disable features, or enter data that can be used in account, billing, or other operations.

Most people are familiar with an IVR as an auto-attendant that answers a main number for your company and provides a list of options to reach people (that is, 'For sales press 1, for support press 2'). This avoids disruptions to unintended call recipients, and reduces or removes the need for a dedicated receptionist. More advanced IVRs can also be used for collecting information from a caller, such as a caller's account number or the PIN number for a conference bridge. In this chapter, we...

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, 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"...

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...

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="bridgesofia/$${domain}/[e-mail]"/>
  <entry action="menu-exec-app" digits="2" param="transfer 9196 XMLdefault"/>
  <entry action="menu-exec-app" digits="3" param="transfer 9664 XMLdefault"/>
  <entry action="menu-exec-app" digits="4" param="transfer 9191 XMLdefault"/>
  <entry action="menu-exec-app" digits="5" param="transfer 1234*256enum"/>
  <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...

Routing calls to your IVR

Routing calls to your IVR is simple and can be done from within the Dialplan. Simply add the following XML application to your Dialplan extension where you want to invoke an IVR:

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

This will cause FreeSWITCH to look for the IVR named demo_ivr and invoke it. Note that it is not possible to return from an IVR and continue processing Dialplan entries; the IVR must ultimately transfer, bridge, or hangup the caller.

The XML Dialplan entry for invoking the demo_ivr, which is included with the sample FreeSWITCH configuration files, is as follows:

<!-- a sample IVR  -->
<extension name="ivr_demo">
  <condition field="destination_number" expression="^5000$">
    <action application="answer"/>
    <action application="sleep" data="2000"/>
    <action application="ivr" data="demo_ivr"/>
  </condition>
</extension>

Note that in the preceding example, a sleep application appears before...

Nesting IVRs

There are two ways to "nest" or otherwise combine IVRs.

The first way is to use the sub-menu system list, as mentioned. Simply create two or more IVR menus as if they were independent menus, with each one having a unique name. Then, from the main IVR, create an entry option with an action of menu-sub and a param containing the name of the child IVR.

  <entry digits="1" action="menu-sub" param="child_ivr"/>

The advantage to creating your menus this way is that you gain the ability to use the menu-back action to allow callers to get to the previous IVR menu, useful if you might have multiple parents calling the same child menu.

The other way to use sub-menus is to assign each IVR a unique extension number and simply transfer the caller from one extension to another, in order to get to and from the parent and child menus. In this way, you can always guarantee that you can get from one specific IVR to another and back again, regardless of how an IVR was invoked.

Using phrases with IVRs

You may have noticed the greet-long and greet-short option in the examples use "phrase:demo_ivr_main_menu" as opposed to a specific sound filename and path. IVRs allow you to specify sound files using the phrase and text-to-speech macros. This is useful for several reasons, most notably the ability to chain together multiple sounds into one "phrase" and the ability to have different languages presented to the caller, based on the caller's information.

Calling Phrase Macros

Phrase Macros can be called from the Dialplan, from an IVR, or from Dialplan script. (The latter will be covered in the next chapter.) Phrase Macros can be used virtually anywhere that a sound filename can be used. (Phrase Macros are used only for playback purposes, so they cannot be used when specifying a filename for a recording operation.) We have already seen examples of using phrases in our XML IVR configuration files. Following are a few examples of using Phrase Macros from the Dialplan:

<...

Advanced routing

IVRs are not just limited to menus. While you most likely want to program complex IVRs using a programming language, it's possible to use the built-in XML IVRs in other ways, too.

For example, let's say you wanted to require callers to enter a PIN number in order to reach a special answering service. You might create an IVR that contains the PIN number as the only available entry, and replace the sound files with a greeting, requesting the PIN number and the invalid entry sound with an invalid password message. The menu would be simple enough as follows:

    <menu name="enter_pin"
          greet-long="phrase:enter_your_pin"
          invalid-sound="phrase:invalid_pin"
          exit-sound="phrase:invalid_pin"
          timeout="15000"
          max-failures="3"
          max-timeouts="3">
      <entry digits="1828" action="menu-exec-app" param="transferafter_hours XML default"/>
    </menu>

This would effectively create a prompt, requesting a password as...

Summary

The IVR system within FreeSWITCH is a powerful, flexible tool for use when creating anything that gathers input from a caller. When combined with the various other applications in FreeSWITCH, the possibilities for routing callers using dynamic and creative call flows are endless. Now that we have considered the XML IVR system and the Phrase Macro system, let's turn our attention to an alternative means of control complex interaction with the caller, that is, Dialplan scripting with the Lua programming language.