2.7. Menus

A menu is a special case of a form so frequently used that the creators of VoiceXML made a shorthand notation for it - the menu element type. A menu is similar to a form with only one question. For example, a banking application might present a menu like:

Would you like to:
  * Check your account balance,
  * Transfer funds, or
  * Speak with a customer service representative?

There is only one question - what does the customer want to do? There are three possible valid answers to this question, namely to check your account balance, to transfer funds, or to speak with a customer service representative.

The menu element type represents this special sort of a form. In VoiceXML, the banking menu described above could be written as in Example 2-47.

Example 2-47. Banking example using the menu element

<menu>
  <prompt>
    Please choose from the following options:
    <enumerate/>
  </prompt>

  <choice dtmf="1" next="#checkBalance">
    Check account balance
  </choice>

  <choice dtmf="2" next="#transferFunds">
    Transfer funds
  </choice>

  <choice dtmf="3" next="#speakWithRep">
    Speak with a customer service representative
  </choice>

  <catch event="nomatch noinput">
    I'm sorry. I didn't understand. Please choose from the following
    options: <enumerate/>
  </catch>
</menu>

A possible interaction scenario with this menu might be as in Example 2-48.

Example 2-48. Possible caller scenario

IVR     : Please choose from the following options:
          For Entry 1, Check account balance,
          please press 1 or say 'Check account balance'.
          For Entry 2, Transfer funds,
          please press 2 or say 'Transfer funds'.
          For Entry 3, Speak with a customer service representative
          please press 3 or say 'Speak with a customer service 
                                 representative'.
Caller  : I don't know.
IVR     : I'm sorry. I didn't understand. Please choose from the 
          following options:
          For Entry 1, Check account balance,
          please press 1 or say 'Check account balance'.
          For Entry 2, Transfer funds,
          please press 2 or say 'Transfer funds'.
          For Entry 3, Speak with a customer service representative
          please press 3 or say 'Speak with a customer service 
                                 representative'.
Caller  : Presses touch tone 3
				

The menu element type introduces some new sub-elements such as choice and enumerate that have no counterparts in a form. Additionally, the interpretation algorithm for a menu is a bit different from the Form Interpretation Algorithm. The following sections will examine these points in depth.

2.7.1. The prompt element type in a menu

A prompt element specifies a message the VoiceXML interpreter should use to introduce the menu options. The contents of prompt are played when the user enters the menu for the first time. If the caller fails to correctly choose a menu option, a nomatch or noinput event will be thrown, but this menu-level prompt will not be re-executed. This is why, in Example 2-47, there is a prompt message in the catch element that is almost identical to that within the prompt element.

2.7.2. The enumerate element type

An enumerate element instructs the VoiceXML interpreter to "intelligently" play the menu options to the user. This default enumeration algorithm should list all the choices based on the contents of the menu's choice elements. The precise algorithm for doing this is not specified and varies from one platform to another. While the scenario above shows a very verbose rendition, another platform may render this enumerate much more simply, for example:

Check your account balance; Transfer funds; 
Speak with a customer service representative.

As the above does not tell the user which DTMF keys to press, we might want to override this default behavior. One can specify a new enumeration behavior in the contents of enumerate, for example:

<enumerate>
  If you would like to <value expr="_prompt"/>,
  please press <value expr="_dtmf"/>.
</enumerate>

The contents of enumerate act as a template for reading off each menu choice. This template takes two variables as parameters, _prompt and _dtmf:

• _prompt contains the contents of the current choice element being read to the caller;

• _dtmf contains the DTMF key associated with thecurrent choice.

This enumerate element should produce the same results on every VoiceXML interpreter, namely:

IVR     : If you would like to Check your account balance, press 1.
          If you would like to Transfer funds, press 2.
          If you would like to speak with a customer service 
          representative, press 3.

2.7.3. The choice element type

A choice element specifies a menu choice. Particularly, each choice element must specify:

• a description of this menu choice that can be read to theuser, such as "Transfer funds,"

• the phrase to be recognized as the user selecting this menu choice, and

• what to do when the user selects this choice.

Example 2-47 specifies the description simply as text. Another option would be embedding audio within a choice element to provide a pre-recorded description of the choice. This choice description is used by enumerate when reading off all of the menu choices.

The grammar can be specified as a DTMF digit, as it is done in Example 2-47, or it can be taken from the textual contents of the choice element. For example:

<choice next="OpenNewAccount.xml">
  Open a new account.
</choice>

If the user answered "Open a new account," this menu choice would be selected. What is actually happening here is the VoiceXML interpreter generating a grammar on the fly to recognize this phrase. The VoiceXML author can tune this grammar generation using the accept attribute. If accept is set to exact, the user would have to utter the exact phrase, "Open a new account." If it were set to approximate, a more loose-fitting grammar would be automatically generated that might recognize other variants of this phrase, such as "open account" or simply "open."

We often need to implement DTMF-driven menus. Specifying a choice element's DTMF attribute associates a DTMF key with this menu choice. This is how the menu in Example 2-47 is implemented.

Once a user selects a menu choice, the VoiceXML interpreter can do one of several things in response:

• jump to a dialog located at a pre-specified URI,

• jump to a dialog located at a URI computed at run time, or

• throw an interpreter event.

Example 2-47 uses the first option. The destination for each menu choice is hard-wired into the VoiceXML document using the choice element's next attribute. When, for example, the user selects the "Speak with a customer service representative" option, the VoiceXML interpreter jumps to the dialog #speakWithRep.

Let's consider an example where we want the caller to go to a different dialog depending on the time of day. Let's assume there is an ECMAScript variable officesOpen that is set to true if the customer service offices are open or false if the offices are closed. We can modify the choice element as follows:

<choice dtmf="3" expr="officesOpen?'#speakWithRep':'#callBack'">
  Speak with a customer service representative.
</choice>

Here, choice's expr attribute contains an ECMAScript expression that evaluates to the destination URI for this menu choice. The ternary ECMAScript expression evaluates to #speakWithRep if officesOpen is true and to #callBack otherwise.

In many deployments, transferring to a customer service representative is integrated into the IVR system. You can activate this built-in behavior by throwing an exit event, indicating to the VoiceXML interpreter that the caller wants to exit the system and speak with a customer service representative. In this case, we could re-write this choice as follows:

<choice dtmf="3" event="exit">
  Speak with a customer service representative.
</choice>

We indicate which event a menu selection should throw with the choice element's event attribute. In this example, when the caller chooses "Speak with a customer service representative," the VoiceXML interpreter will throw a exit event.

2.7.4. Shorthand for specifying DTMF menu choice input grammars

The menu element type provides the dtmf attribute as a convenient shorthand for automatically generating DTMF grammars for all the choices. If you define this attribute as true, the VoiceXML interpreter will automatically assign successive DTMF input values to each choice where there is no explicit DTMF assignment. For example, the bank menu in Example 2-47 can be rewritten as in Example 2-49.

Example 2-49. Banking menu with automatic DTMF assignments

<menu dtmf="true">
  <prompt>
    Please choose from the following options:
    <enumerate>
      If you would like to <value expr="_prompt"/>,
      please press <value expr="_dtmf"/>.
    </enumerate>
  </prompt>

  <choice next="#checkBalance">
    Check your account balance.
  </choice>

  <choice next="#transferFunds">
    Transfer funds.
  </choice>

  <choice expr="officesOpen?'#speakWithRep':'#callBack'">
    Speak with a customer service representative.
  </choice>

  <catch event="nomatch noinput">
    I'm sorry. I didn't understand. <enumerate/>
  </catch>
</menu>

Let's consider the situation where we want to automatically number every choice in the menu except the "Speak with a customer service representative" choice, which we want to always be mapped to DTMF "0". We can do this simply by specifying the dtmf attribute on this choice.

<choice dtmf="0" expr="officesOpen?'#speakWithRep':'#callBack'">
  Speak with a customer service representative.
</choice>

The other choices will still be assigned automatically, and the VoiceXML interpreter will take care as to not automatically assign the DTMF value of "0" to any of the other choices.

2.7.5. Handling user errors

Like a form, a menu can have catch elements for events like noinput and nomatch. This allows us to control the menu behavior when the user fails to correctly choose a menu choice. The body of the catch element in Example 2-47 tells the user that his or her utterance was not understood, and then uses the enumerate element to remind the user of the valid choices for this menu.

Despite the specification, some interpreter implementations vary as to what they do after executing the contents of a catch. Some will simply wait for the user to try again, while others will replay the prompt. The specification indicates that the catch block should be executed as if copied into the field's execution context.

2.7.6. Menu or form?

Recall from the previous section that a menu is just a special case of a form. It can be thought of as a shorthand for the commonly used, but limited scenario of a form with a single field - one that only asks a single question - and a small finite list of possible valid answers.

Table 2-1 offers some very high-level rules of thumb as to whether a menu or a form better suits your application.

^[†] Note that this can be accomplished with forms as well but requires a few tricks. See 2.6, “Mixed initiative forms,” on page 76.