Recognizing User Input

While the Hello, world sample demonstrates the simplest phone application imaginable, a useful voice application typically requirs some level of interactivity between the caller and the system. This example shows the basics of recognizing caller commands using touch-tone (DTMF) and spoken input.

Try It!
  1. Set your Application URL to http://studio.247-inc.net/library2/code/ex-102/index.vxml
  2. Call the number shown in VXML Tools page
  3. Sign in, and play!

How it works

In VoiceXML, use the field element to add interactivity to your voice application. Just as a textbox on an HTML page receives keyboard input from the user, a field in a VoiceXML document receives spoken or touch-tone (DTMF) input. When user input is recognized by the voice recognition engine, the Voice Browser sets the variable associated with the value of the name attribute of the field element. In this sample, for instance, if the user says "dogs" or "pet department", the variable dept is set to the value "dog."

Once the field item variable is set, the VoiceXML interpreter executes the filled element where your application can perform further input-specific logic. In the sample, the application navigates to a department-specific dialog based on the user's response. While this example does nothing more than announce the department to the user and navigate back to the choose_dept dialog, you could extend the example to prompt the user for a specific dog in the dog_dept dialog and for a specific plant in the plant_dept dialog.

To provide the user with a complete interactive experience, the field element in the choose_dept dialog includes the following elements:

grammar Specifies the set of allowable user inputs. The recognition system that underlies the VoiceXML interpreter cannot listen for arbitrary inputs and then take a "best guess" at what the caller said. The recognition system must know ahead of time the allowable inputs it should expect, although the grammar size can be very large.
prompt Asks a caller for input, such as "Say the name of a restaurant" or "Say or dial a ten digit phone number".
nomatch Executes whenever the caller provides an input which is not found in the active grammars. In the choose_dept dialog, the active grammars include the department grammar as well as the grammars associated with the link elements defined at document scope.
noinput Executes whenever the caller fails to provide any input in response to a prompt within the designated timeout period.
help Executes whenever the caller utters the word help or types "0" on the keypad as defined in the grammar associated with the help link.
filled Executes when the caller provides a recognized spoken or DTMF input, the filled section becomes active. This element is primarily used to determine the application control in response to a caller command.

This sample also includes support for a "quit" command. As defined in the link associated with the quit grammar, the VoiceXML interpreter navigates to the system main menu.

VoiceXML 2.0 Code

The VoiceXML code for this example follows:

<?xml version="1.0"?>
<!--
Tellme Studio Code Example 102
Copyright (C) 2000-2001 Tellme Networks, Inc. All Rights Reserved.

THIS CODE IS MADE AVAILABLE SOLELY ON AN "AS IS" BASIS, WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION,
WARRANTIES THAT THE CODE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A
PARTICULAR PURPOSE OR NON-INFRINGING.
-->

<vxml version="2.0">

<!-- document-level link fires a help event -->
<link event="help">
  <grammar mode="dtmf"
           root="root_rule"
           tag-format="semantics/1.0"
           type="application/srgs+xml"
           version="1.0">
    <rule id="root_rule" scope="public">
      <item>
        0
      </item>
    </rule>
  </grammar>

  <grammar mode="voice"
           root="root_rule"
           tag-format="semantics/1.0"
           type="application/srgs+xml"
           version="1.0"
           xml:lang="en-US">
    <rule id="root_rule" scope="public">
      <item weight="0.001">
        help
      </item>
    </rule>
  </grammar>
</link>



<!-- document-level link quits -->
<link event="event.exit">
  <grammar mode="voice"
           root="root_rule"
           tag-format="semantics/1.0"
           type="application/srgs+xml"
           version="1.0"
           xml:lang="en-US">
    <rule id="root_rule" scope="public">
      <one-of>
        <item>
          quit
        </item>
      </one-of>
    </rule>
  </grammar>
</link>


<catch event="event.exit">
   <exit />
</catch>

<!-- this form asks the user to choose a department -->
<form id="choose_dept">

   <!-- dept is the field item variable that 
        holds the return value from the grammar -->
   <field name="dept">      
      
      <grammar mode="dtmf"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0">
            <rule id="root_rule" scope="public">
                  <one-of>
                        <item>
                              <item>
                                    1
                              </item>
                              <tag>out.dept = "dog";</tag>
                        </item>
                        <item>
                              <item>
                                    2
                              </item>
                              <tag>out.dept = "plant";</tag>
                        </item>
                  </one-of>
            </rule>

      </grammar>

      <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
            <rule id="root_rule" scope="public">
                  <one-of>
                        <item>
                              <one-of>
                                    <item>
                                          dogs
                                    </item>
                                    <item>
                                          <one-of>
                                                <item>
                                                      dog
                                                </item>
                                                <item>
                                                      canine
                                                </item>
                                                <item>
                                                      pet
                                                </item>
                                                <item>
                                                      mutt
                                                </item>
                                          </one-of>
                                          <item repeat="0-1">
                                                department
                                          </item>
                                    </item>
                              </one-of>
                              <tag>out.dept = "dog";</tag>
                        </item>
                        <item>
                              <one-of>
                                    <item>
                                          plants
                                    </item>
                                    <item>
                                          flowers
                                    </item>
                                    <item>
                                          nursery
                                    </item>
                                    <item>
                                          <one-of>
                                                <item>
                                                      plant
                                                </item>
                                                <item>
                                                      flower
                                                </item>
                                          </one-of>
                                          <item repeat="0-1">
                                                department
                                          </item>
                                    </item>
                              </one-of>
                              <tag>out.dept = "plant";</tag>
                        </item>
                  </one-of>
            </rule>

      </grammar>

      
      <prompt>
         <audio>Would you like to buy a dog or a plant?</audio>
      </prompt>

      <!-- User's utterance didn't match the grammar  -->      
      <nomatch>
         <audio>Sorry, I didn't understand</audio>
         <reprompt/>
      </nomatch>

      <!-- User was silent -->
      <noinput>
         <audio>Sorry, I didn't hear you</audio>
         <reprompt/>
      </noinput>
      
      <!-- User said help -->
      <help>
         <audio>
            You are in Buy Me. Please choose a department. You can
            say dogs or plants. You can also say quit at any time.
         </audio> 
      </help>
      
      <!-- User's utterance matched the grammar -->
      <filled>
         <audio>I heard you say <value expr="dept"/></audio>

         <if cond=" dept == 'dog' ">
            <goto next="#dog_dept"/>
         <elseif cond=" dept == 'plant' "/>
            <goto next="#plant_dept"/>
         </if>
      </filled>
   </field>
</form>

<!-- 
   The following two dialogs (dog_dept and plant_dept) don't accept user input.
   You can make them more useful by allowing the user to choose from a list of items 
   appropriate for the dialog (aka department).
-->

<form id="dog_dept">
   <block>
        <audio>Welcome to the dog department!</audio>
        <!-- TODO: add code to choose a type of dog -->
        <goto next="#choose_dept"/>
   </block>
</form>

<form id="plant_dept">
   <block>
        <audio>Welcome to the plant department</audio>
        <!-- TODO: add code to choose a type of plant -->
        <goto next="#choose_dept"/>
   </block>
</form>

</vxml>