# <choice>

Description

Defines a menu item. The `<choice>` element serves several purposes:

- Specifies a speech grammar fragment and/or a DTMF grammar fragment to determine when that choice has been selected.
- Specifies what to do when that choice has been selected.
- Uses the contents to form the `<enumerate>` prompt string.

Syntax

    <choice
        dtmf="DTMF_sequence"
        accept="exact" | "approximate"
        next="URI"
        expr="ECMAScript_Expression"
        event="event"
        eventexpr="ECMAScript_Expression"
        fetchaudio="URI"
        fetchaudiodelay="time_interval"
        fetchaudiominimum="time_interval"
        fetchhint="safe"
        fetchtimeout="time_interval"
        maxage="integer"
        maxstale="integer"
        message="string"
        messageexpr="ECMAScript_Expression">
      child elements
    </choice>

Attributes

Attribute | Description
dtmf | A DTMF sequence to select this choice. Optional.
accept | Overrides the setting for the `accept` attribute in `<menu>`. Optional. (Defaults to exact.) exact - The text contained in the `<choice>` element defines the exact phrase to be recognized. approximate - The text contained in the `<choice>` element defines an approximate recognition phrase. A subset of the words in the phrase can be matched. For example, "hello world" can be matched with "hello world", "hello", or "world".
next | The URI of the dialog (i.e. form or menu) or document to transition to when this choice is selected. Exactly one of next, expr, event, or eventexpr must be specified.
expr | An ECMAScript expression to be evaluated and used as the URI of the dialog (i.e. form or menu) or document to transition to when this choice is selected. Exactly one of next, expr, event, or eventexpr must be specified; next has precedence over this attribute.
event | The name of the event to be thrown when this choice is selected. Exactly one of next, expr, event, or eventexpr must be specified; next and expr have precedence over this attribute.
eventexpr | An ECMAScript expression to be evaluated and used as the name of the event to be thrown when this choice is selected. Exactly one of next, expr, event, or eventexpr must be specified; next and expr have precedence over this attribute.
fetchaudio | The URI of audio to play while waiting for the document to be fetched. Optional.
fetchaudiodelay | The length of time to wait at the start of the fetch delay before playing `fetchaudio`. Optional.
fetchaudiominimum | The minimum length of time to play `fetchaudio`, once started, even if the document arrives in the meantime. Optional.
fetchhint | Defines when the next document should be fetched. Optional. safe - only load the next document when needed
fetchtimeout | The length of time to wait for the next document to be fetched before throwing an `error.badfetch` event. Optional.
maxage | Indicates that this document is willing to use a cached copy of the next document only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute. Optional.
maxstale | Indicates that this document is willing to use a cached copy of the next document that has exceeded its expiration time by as much as the number of seconds specified by this attribute. Optional.
message | A message string providing additional context about the event being thrown. The message will be available as a variable within the scope of the `<catch>` element. Optional. (Can only be used if event or eventexpr is specified; only one of message or messageexpr can be specified.)
messageexpr | An ECMAScript expression to be evaluated and used as a message string, as documented under `message`, above. Optional. (Can only be used if event or eventexpr is specified; only one of message or messageexpr can be specified.)

Attribute Notes

- An `error.badfetch` event is thrown if `next` or `expr` refer to a non-existent dialog (i.e. form or menu), either within the same page, or within a different, existent, page.

Parents

<menu>

Children

<audio>, <dtmf>, <grammar>, <value>, Speech Markup (SSML), #PCDATA

extensions

- Added `fetchaudiodelay` attribute.
- Added `fetchaudiominimum` attribute.
- Added `<dtmf>` as a child, to be used like `<grammar>`.
- Added `<audio>`, `<value>`, and Speech Markup (SSML) tags as children, to be used in the `<enumerate>` prompt string (but not in the speech grammar fragment).

Limitations/Restrictions

- Currently, `<mark>` is not supported within SSML content in `<choice>`.

Example

    <?xml version="1.0"?>
    <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
      <menu>
        <prompt> What do you want to drink, coffee or tea? </prompt>
        <choice next="#getcoffee"> coffee </choice>
        <choice next="#gettea"> tea </choice>
      </menu>
      <form id="getcoffee">
        <block>
          Ok, here's your coffee.
        </block>
      </form>
      <form id="gettea">
        <block>
          Ok, here's your tea.
        </block>
      </form>
    </vxml>