choice element
Last Updated: 11-07-2005
VoiceXML 2.0
Defines a menu option.

Syntax

<choice
accept = "integer"
dtmf = "integer"
event = "string"
eventexpr = "ECMAScript_Expression"
expr = "ECMAScript_Expression"
fetchaudio = "URI"
fetchaudioexpr = "ECMAScript_Expression"
fetchhint = "string"
fetchtimeout = "string"
maxage = "seconds"
maxstale = "seconds"
message = "string"
messageexpr = "ECMAScript_Expression"
next = "URI"
/>

Attributes
accept
One of the following values:
approximate The user utterance need only match a sub-phrase of the grammar fragment in order for a recognition match to occur.
exact The user utterance must match every word of the grammar fragment in order for a recognition match to occur.
dtmf
The DTMF sequence for this choice. When user input matches the DTMF sequence, the next, expr, event, or eventexpr attribute is executed. DTMF properties apply to recognition of the sequence. Whitespace is optional: "123# is equivalent to "1 2 3 #". If the dtmf attribute of the parent menu element is set to "true", the dtmf attribute of the choice element may only be set to "*", "#", or "0". If another value is specified, the interpreter throws error.badfetch.
event
The event to throw.
eventexpr
An ECMAScript expression that evaluates to the name of the event to throw.
expr
An ECMAScript expression that evaluates to the URI of the document or anchor to jump to if the user's utterance matches the grammar fragment.
fetchaudio
The URI of the audio clip to play while the interpreter fetches the resource. For complete details on the proper use of this attribute, read the fetchaudio tutorial.
fetchaudioexpr
An ECMAScript expression that evaluates to the URI used for fetchaudio. This attribute is a Tellme extension.
fetchhint
Defines when the interpreter context may retrieve documents from the server.
prefetch Documents may be prefetched.
safe Documents may only be fetched when needed, never before.
fetchtimeout
The time in seconds (s) or milliseconds (ms) for the VoiceXML interpreter to wait for content to be returned by the HTTP server before throwing an error.badfetch event. The fetchtimeout value is rounded down to the nearest whole second (e.g., 5700ms or 5.7s would be rounded down to 5s). If fetchtimeout has a value less than 1 second, it is reset to the default value. The default value is 15s.
maxage
Sends the max-age Cache-Control HTTP header along with the request for the specified resource. The header indicates that the document is willing to use content whose age is no greater than the specified time in seconds, unless maxstale is also provided.
Voice application developers should use extreme caution when setting this attribute. If used improperly, it could have an adverse affect on the performance of your application. You should only consider using this attribute in requests for frequently changing content (e.g. dynamically generated content) hosted on a misconfigured HTTP server that you do not control. To reduce load, some HTTP servers are configured to indicate to clients that content expires some arbitrary time in the future. In that case, set the maxage attribute to 0. If you do control the HTTP server, you should instead configure the HTTP server to omit the expires header and possibly to send the Cache-Control: no-cache header. The former requires the VoiceXML interpreter to check with the server before using any cached content. The latter requires the VoiceXML interpreter to not cache the fetched resource.
maxstale
Instructs the VoiceXML interpreter to send a max-stale Cache-Control header along with the HTTP request for the specified resource. The header indicates that the document is willing to use content that has exceeded its expiration time by no more than the specified number of seconds.
Voice application developers should use extreme caution when setting this attribute. If used improperly, your application may present stale content to users. If you do control the HTTP server, you should instead configure the HTTP server to send an expires header with a time in the distant future.
message
Additional information about the event being thrown. The string is available as the value of the _message variable within the scope of the event handler.
messageexpr
An ECMAScript expression that evaluates to a message string.
next
The URI of the document (or anchor within the current document) to jump to if the user's utterance matches the grammar fragment.

Parents
menu

Children
grammar

Remarks
The choice element specifies a speech or DTMF grammar fragment and an event to fire or a location to transition to when a recognition match occurs. The choice element works in conjunction with the prompt element, which prompts the user for specific input in the form of a list of choices.
The event, next, expr and eventexpr attributes are mutually exclusive.
Specifying an explicit dtmf attribute on a choice element overrides the default assignment provided by setting the dtmf attribute on the menu element to true.
The accept on the choice element overrides the accept attribute on the menu.
The message and messageexpr attributes are mutually exclusive.
If any of the fetchtimeout, fetchhint, maxage, or maxstale attributes is not specified for a choice element, then the value of the fetchtimeout, documentfetchhint, documentmaxage, or documentmaxstale property, respectively, is used.
The fetchaudio and fetchaudioexpr attributes are mutually exclusive. If both of these attributes are specified an error.badfetch event is thrown.
Examples

The following example includes a menu that offers three choices. The grammar fragment specified for each choice element corresponds to one item from the prompt list. To hear the sports report, the user can say "E S P N sports", "E S P N" or "sports" because the accept attribute allows for approximate matches. To hear news, the user can say "Caltech news" or "news". To hear a weather report, the user can say "Bay Area weather" or "weather."

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
  <!-- only say welcome the first time -->
  <form id="intro">
     <block>
        Welcome
        <goto next="#read_news"/>
     </block>
  </form>

  <menu id="read_news">
    <prompt>
      Say E S P N sports, weather, Caltech news, or quit.
    </prompt>

    <choice next="#sports_report" accept="approximate">(e s p n) sports</choice>

    <choice next="#news_report">?caltech news</choice>

    <choice next="#weather_report">[(bay area)] weather</choice>

    <choice next="#exit">quit</choice>

    <catch event="nomatch noinput help">
      <reprompt />
    </catch>
  </menu>

  <form id="exit">
  <block>
     <exit />
  </block>
  </form>

  <form id="sports_report">
    <block>
      The New York Giants will win the Superbowl next year!
      <goto next="#read_news"/>
    </block>
  </form>

  <form id="weather_report">
    <block>
      It will be mostly clear and sunny today
      <goto next="#read_news"/>
    </block>
  </form>

  <form id="news_report">
    <block>
      Earthquake in California causes damages in the billions
      <goto next="#read_news"/>
    </block>
  </form>
</vxml>


[24]7 Inc.| Terms of Service| Privacy Policy| General Disclaimers