Attributes of

Attributes of

Exactly one of "src" or "expr" must be specified; otherwise, an error.badfetch event is thrown.

Note that it is a platform optimization to stream audio: i.e. the platform may begin processing audio content as it arrives and not to wait for full retrieval. The "prefetch" fetchhint can be used to request full audio retrieval prior to playback.

4.1.4 Element

The element is used to insert the value of an expression into a prompt. It has one attribute:

For example if n is 12, the prompt

   is the square of .

will result in the text string "144 is the square of 12" being passed to the speech synthesis engine.

The manner in which the value attribute is played is controlled by the surrounding speech synthesis markup. For instance, a value can be played as a date in the following example:

The text inserted by the element is not subject to any special interpretation; in particular, it is not parsed as an [SSML] document or document fragment. XML special characters (&, >, and <) are not treated specially and do not need to be escaped. The equivalent effect may be obtained by literally inserting the text computed by the element in a CDATA section. For example, when the following variable assignment:

is referenced in a prompt element as

   The price of  is $1. 

the following output is produced.

 The price of AT&T is $1.

4.1.5 Bargein

If an implementation platform supports bargein, the application author can specify whether a user can interrupt, or "bargein" on, a prompt using speech or DTMF input. This speeds up conversations, but is not always desired. If the application author requires that the user must hear all of a warning, legal notice, or advertisement, bargein should be disabled. This is done with the bargein attribute:

Users can interrupt a prompt whose bargein attribute is true, but must wait for completion of a prompt whose bargein attribute is false. In the case where several prompts are queued, the bargein attribute of each prompt is honored during the period of time in which that prompt is playing. If bargein occurs during any prompt in a sequence, all subsequent prompts are not played (even those whose bargein attribute is set to false). If the bargein attribute is not specified, then the value of the bargein property is used if set.

When the bargein attribute is false, input is not buffered while the prompt is playing, and any DTMF input buffered in a transition state is deleted from the buffer (Section 4.1.8 describes input collection during transition states).

Note that not all speech recognition engines or implementation platforms support bargein. For a platform to support bargein, it must support at least one of the bargein types described in Section 4.1.5.1.

4.1.5.1 Bargein type

When bargein is enabled, the bargeintype attribute can be used to suggest the type of bargein the platform will perform in response to voice or DTMF input. Possible values for this attribute are:

If the bargeintype attribute is not specified, then the value of the bargeintype property is used. Implementations that claim to support bargein are required to support at least one of these two types. Mixing these types within a single queue of prompts can result in unpredictable behavior and is discouraged.

In the case of "speech" bargeintype, the exact meaning of "speech input" is necessarily implementation-dependent, due to the complexity of speech recognition technology. It is expected that the prompt will be stopped as soon as the platform is able to reliably determine that the input is speech. Stopping the prompt as early as possible is desireable because it avoids the "stutter" effect in which a user stops in mid-utterance and re-starts if he does not believe that the system has heard him.

4.1.6 Prompt Selection

Tapered prompts are those that may change with each attempt. Information-requesting prompts may become more terse under the assumption that the user is becoming more familiar with the task. Help messages become more detailed perhaps, under the assumption that the user needs more help. Or, prompts can change just to make the interaction more interesting.

Each input item, , and menu has an internal prompt counter that is reset to one each time the form or menu is entered. Whenever the system selects a given input item in the select phase of FIA and FIA does perform normal selection and queuing of prompts (i.e., as described in Section 5.3.6, the previous iteration of FIA did not end with a catch handler that had no reprompt), the input item's associated prompt counter is incremented. This is the mechanism supporting tapered prompts.

For instance, here is a form with a form level prompt and field level prompts:

 


  
    
      Welcome to the ice cream survey.
    
  
  
  
    
      
        vanilla 
        chocolate
        strawberry
     
    
   
   What is your favorite flavor?
   Say chocolate, vanilla, or strawberry.
   Sorry, no help is available.
  

A conversation using this form follows:

C: Welcome to the ice cream survey.

C: What is your favorite flavor? (the "flavor" field's prompt counter is 1)

H: Pecan praline.

C: I do not understand.

C: What is your favorite flavor? (the prompt counter is now 2)

H: Pecan praline.

C: I do not understand.

C: Say chocolate, vanilla, or strawberry. (prompt counter is 3)

H: What if I hate those?

C: I do not understand.

C: Say chocolate, vanilla, or strawberry. (prompt counter is 4)

H: ...

This is just an example to illustrate the use of prompt counters. A polished form would need to offer a more extensive range of choices and to deal with out of range values in more flexible way.

When it is time to select a prompt, the prompt counter is examined. The child prompt with the highest count attribute less than or equal to the prompt counter is used. If a prompt has no count attribute, a count of "1" is assumed.

A conditional prompt is one that is spoken only if its condition is satisfied. In this example, a prompt is varied on each visit to the enclosing form.

 


   
   
       
       
          Would you like to hear another elephant joke?
       
       
         For another joke say yes.  To exit say no.
       
       
          
            
          
       
   

When a prompt must be chosen, a set of prompts to be queued is chosen according to the following algorithm:

1. Form an ordered list of prompts consisting of all prompts in the enclosing element in document order.
2. Remove from this list all prompts whose cond evaluates to false after conversion to boolean.
3. Find the "correct count": the highest count among the prompt elements still on the list less than or equal to the current count value.
4. Remove from the list all the elements that don't have the "correct count".

All elements that remain on the list will be queued for play.

4.1.7 Timeout

The timeout attribute specifies the interval of silence allowed while waiting for user input after the end of the last prompt. If this interval is exceeded, the platform will throw a noinput event. This attribute defaults to the value specified by the timeout property (see Section 6.3.4) at the time the prompt is queued. In other words, each prompt has its own timeout value.

The reason for allowing timeouts to be specified as prompt attributes is to support tapered timeouts. For example, the user may be given five seconds for the first input attempt, and ten seconds on the next.

The prompt timeout attribute determines the noinput timeout for the following input:

  Pick a color for your new Model T.



  Please choose color of your new nineteen twenty four
  Ford Model T. Possible colors are black, black, or
  black.  Please take your time.

If several prompts are queued before a field input, the timeout of the last prompt is used.

4.1.8 Prompt Queueing and Input Collection

A VoiceXML interpreter is at all times in one of two states:

• waiting for input in an input item (such as , , or ), or
• transitioning between input items in response to an input (including spoken utterances, dtmf key presses, and input-related events such as a noinput or nomatch event) received while in the waiting state. While in the transitioning state no speech input is collected, accepted or interpreted. Consequently root and document level speech grammars (such as defined in s) may not be active at all times. However, DTMF input (including timing information) should be collected and buffered in the transition state. Similarly, asynchronously generated events not related directly to execution of the transition should also be buffered until the waiting state (e.g. connection.disconnect.hangup).

The waiting and transitioning states are related to the phases of the Form Interpretation Algorithm as follows:

• the waiting state is eventually entered in the collect phase of an input item (at the point at which the interpreter waits for input), and
• the transitioning state encompasses the process and select phases, the collect phase for control items (such as s), and the collect phase for input items up until the point at which the interpreter waits for input.

This distinction of states is made in order to greatly simplify the programming model. In particular, an important consequence of this model is that the VoiceXML application designer can rely on all executable content (such as the content of and elements) being run to completion, because it is executed while in the transitioning state, which may not be interrupted by input.

While in the transitioning state various prompts are queued, either by the element in executable content or by the element in form items. In addition, audio may be queued by the fetchaudio attribute. The queued prompts and audio are played either

• when the interpreter reaches the waiting state, at which point the prompts are played and the interpreter listens for input that matches one of the active grammars, or
• when the interpreter begins fetching a resource (such as a document) for which fetchaudio was specified. In this case the prompts queued before the fetchaudio are played to completion, and then, if the resource actually needs to be fetched (i.e. it is not unexpired in the cache), the fetchaudio is played until the fetch completes. The interpreter remains in the transitioning state and no input is accepted during the fetch.

Note that when a prompt's bargein attribute is false, input is not collected and DTMF input buffered in a transition state is deleted (see Section 4.1.5).

When an ASR grammar is matched, if DTMF input was consumed by a simultaneously active DTMF grammar (but did not result in a complete match of the DTMF grammar), the DTMF input may, at processor discretion, be discarded.

Before the interpreter exits all queued prompts are played to completion. The interpreter remains in the transitioning state and no input is accepted while the interpreter is exiting.

It is a permissible optimization to begin playing prompts queued during the transitioning state before reaching the waiting state, provided that correct semantics are maintained regarding processing of the input audio received while the prompts are playing, for example with respect to bargein and grammar processing.

The following examples illustrate the operation of these rules in some common cases.

Case 1

Typical non-fetching case: field, followed by executable content (such as and ), followed by another field.

 in document d0

    

    
        executable content e1
        queues prompts {p1}
    

    
        queues prompts {p2}
        enables grammars {g2}
    

As a result of input received while waiting in field f0 the following actions take place:

• in transitioning state
  • execute e1 (without goto)
  • queue prompts {p1}
  • queue prompts {p2}
• in waiting state, simultaneously
  • play prompts {p1,p2}
  • enable grammars {g2} and wait for input

Case 2

Typical fetching case: field, followed by executable content (such as and ) ending with a that specifies fetchaudio, ending up in a field in a different document that is fetched from a server.

 in document d0

    

    
        executable content e1
        queues prompts {p1}
        ends with goto f2 in d1 with fetchaudio fa
    

in document d1

    
        queues prompts {p2}
        enables grammars {g2}
    

As a result of input received while waiting in field f0 the following actions take place:

• in transitioning state
  • execute e1
  • queue prompts {p1}
  • simultaneously
    • fetch d1
    • play prompts {p1} to completion and then play fa until fetch completes
  • queue prompts {p2}
• in waiting state, simultaneously
  • play prompts {p2}
  • enable grammars {g2} and wait for input

Case 3

As in Case 2, but no fetchaudio is specified.

 in document d0

    

    
        executable content e1
        queues prompts {p1}
        ends with goto f2 in d1 (no fetchaudio specified)
    

in document d1

    
        queues prompts {p2}
        enables grammars {g2}
    

As a result of input received while waiting in field f0 the following actions take place:

• in transitioning state
  • execute e1
  • queue prompts {p1}
  • fetch d1
  • queue prompts {p2}
• in waiting state, simultaneously
  • play prompts {p1, p2}
  • enable grammars {g2} and wait for input

5. Control flow and scripting

5.1 Variables and Expressions

VoiceXML variables are in all respects equivalent to ECMAScript variables: they are part of the same variable space. VoiceXML variables can be used in a

5.2 Event Handling

The platform throws events when the user does not respond, doesn't respond in a way that the application understands, requests help, etc. The interpreter throws events if it finds a semantic error in a VoiceXML document, or when it encounters a element. Events are identified by character strings.

Each element in which an event can occur has a set of catch elements, which include:

An element inherits the catch elements ("as if by copy") from each of its ancestor elements, as needed. If a field, for example, does not contain a catch element for nomatch, but its form does, the form's nomatch catch element is used. In this way, common event handling behavior can be specified at any level, and it applies to all descendents.

The "as if by copy" semantics for inheriting catch elements implies that when a catch element is executed, variables are resolved and thrown events are handled relative to the scope where the original event originated, not relative to the scope that contains the catch element. For example, consider a catch element that is defined at document scope handling an event that originated in a within the document. In such a catch element variable references are resolved relative to the 's scope, and if an event is thrown by the catch element it is handled relative to the . Similarly, relative URI references in a catch element are resolved against the active document and not relative to the document in which they were declared. Finally, properties are resolved relative to the element where the event originated. For example, a prompt element defined as part of a document level catch would use the innermost property value of the active form item to resolve its timeout attribute if no value is explicitly specified.

5.2.1 throw element

The element throws an event. These can be the pre-defined ones:

or application-defined events:

Attributes of are:

Exactly one of "event" or "eventexpr" must be specified; otherwise, an error.badfetch event is thrown. Exactly one of "message" or "messageexpr" may be specified; otherwise, an error.badfetch event is thrown.

Unless explicited stated otherwise, VoiceXML does not specify when events are thrown.

5.2.2 catch element

The catch element associates a catch with a document, dialog, or form item (except for blocks). It contains executable content.

   
    What is your username 
  
   
    What is the code word? 
    
     rutabaga
    
   It is the name of an obscure vegetable. 
    
     Security violation! 
      
    
   

The catch element's anonymous variable scope includes the special variable _event which contains the name of the event that was thrown. For example, the following catch element can handle two types of events:

The _event variable is inspected to select the audio to play based on the event that was thrown. The foo.wav file will be played for event.foo events. The bar.wav file will be played for event.bar events. The remainder of the catch element contains executable content that is common to the handling of both event types.

The catch element's anonymous variable scope also includes the special variable _message which contains the value of the message string from the corresponding element, or a platform-dependent value for the pre-defined events raised by the platform. If the thrown event does not specify a message, the value of _message is ECMAScript undefined.

If a element contains a element with the same event, then there may be an infinite loop:

A platform could detect this situation and throw a semantic error instead.

Attributes of are:

5.2.3 Shorthand Notation

The , , , and elements are shorthands for very common types of elements.

The element is short for and catches all events of type error:

  An error has occurred -- please call again later.
  

The element is an abbreviation for :

No help is available.

The element abbreviates :

I didn't hear anything, please try again.

And the element is short for :

I heard something, but it wasn't a known city.

These elements take the attributes:

5.2.4 catch element selection

An element inherits the catch elements ("as if by copy") from each of its ancestor elements, as needed. For example, if a element inherits a element from the document

    


    
        Please say a primary color
    red | yellow | blue
        
            
        
    

then the element is implicitly copied into as if defined below:

    
        Please say a primary color
    red | yellow | blue
        
            
        
        
            
    

When an event is thrown, the scope in which the event is handled and its enclosing scopes are examined to find the best qualified catch element, according to the following algorithm:

1. Form an ordered list of catches consisting of all catches in the current scope and all enclosing scopes (form item, form, document, application root document, interpreter context), ordered first by scope (starting with the current scope), and then within each scope by document order.
2. Remove from this list all catches whose event name does not match the event being thrown or whose cond evaluates to false after conversion to boolean.
3. Find the "correct count": the highest count among the catch elements still on the list less than or equal to the current count value.
4. Select the first element in the list with the "correct count".

The name of a thrown event matches the catch element event name if it is an exact match, a prefix match or if the catch event attribute is not specified (note that the event attribute cannot be specified as an empty string - event="" is syntactically invalid). A prefix match occurs when the catch element event attribute is a token prefix of the name of the event being thrown, where the dot is the token separator, all trailing dots are removed, and a remaining empty string matches everything. For example,

   Caught a connection dot disconnect event

will prefix match the event connection.disconnect.transfer.

   Caught a com dot example dot my event

prefix matches com.example.myevent.event1., com.example.myevent. and com.example.myevent..event1 but not com.example.myevents.event1. Finally,

   Caught an event

prefix matches all events (as does without an event attribute).

Note that the catch element selection algorithm gives priority to catch elements that occur earlier in a document over those that occur later, but does not give priority to catch elements that are more specific over those that are less specific. Therefore is generally advisable to specify catch elements in order from more specific to less specific. For example, it would be advisable to specify catch elements for "error.foo" and "error" in that order, as follows:

 
  Caught an error dot foo event
 
 
  Caught an error event 

If the catch elements were specified in the opposite order, the catch element for "error.foo" would never be executed.

5.2.5 Default catch elements

The interpreter is expected to provide implicit default catch handlers for the noinput, help, nomatch, cancel, exit, and error events if the author did not specify them.

The system default behavior of catch handlers for various events and errors is summarized by the definitions below that specify (1) whether any audio response is to be provided, and (2) how execution is affected. Note: where an audio response is provided, the actual content is platform dependent.

Specific platforms will differ in the default prompts presented.

5.2.6 Event Types

There are pre-defined events, and application and platform-specific events. Events are also subdivided into plain events (things that happen normally), and error events (abnormal occurrences). The error naming convention allows for multiple levels of granularity.

A conforming browser may throw an event that extends a pre-defined event string so long as the event contains the specified pre-defined event string as a dot-separated exact initial substring of its event name. Applications that write catch handlers for the pre-defined events will be interoperable. Applications that write catch handlers for extended event names are not guaranteed interoperability. For example, if in loading a grammar file a syntax error is detected the platform must throw "error.badfetch". Throwing "error.badfetch.grammar.syntax" is an acceptable implementation.

Components of event names in italics are to be substituted with the relevant information; for example, in error.unsupported.element, element is substituted with the name of VoiceXML element which is not supported such as error.unsupported.transfer. All other event name components are fixed.

Further information about an event may be specified in the "_message" variable (see Section 5.2.2).

The pre-defined events are:

cancel

The user has requested to cancel playing of the current prompt.

connection.disconnect.hangup

The user has hung up.

connection.disconnect.transfer

The user has been transferred unconditionally to another line and will not return.

exit

The user has asked to exit.

help

The user has asked for help.

noinput

The user has not responded within the timeout interval.

nomatch

The user input something, but it was not recognized.

maxspeechtimeout

The user input was too long exceeding the 'maxspeechtimeout' property.

In addition to transfer errors (Section 2.3.7.3), the pre-defined errors are:

error.badfetch

The interpreter context throws this event when a fetch of a document has failed and the interpreter context has reached a place in the document interpretation where the fetch result is required. Fetch failures result from unsupported scheme references, malformed URIs, client aborts, communication errors, timeouts, security violations, unsupported resource types, resource type mismatches, document parse errors, and a variety of errors represented by scheme-specific error codes.

If the interpreter context has speculatively prefetched a document and that document turns out not to be needed, error.badfetch is not thrown.  Likewise if the fetch of an

When an interpreter context is transitioning to a new document, the interpreter context throws error.badfetch on an error until the interpreter is capable of executing the new document, but again only at the point in time where the new document is actually needed, not before. Whether or not variable initialization is considered part of executing the new document is platform-dependent.

error.badfetch.http.response_code
error.badfetch.protocol.response_code

In the case of a fetch failure, the interpreter context must use a detailed event type telling which specific HTTP or other protocol-specific response code was encountered. The value of the response code for HTTP is defined in [RFC2616]. This allows applications to differentially treat a missing document from a prohibited document, for instance. The value of the response code for other protocols (such as HTTPS, RTSP, and so on) is dependent upon the protocol.

error.semantic

A run-time error was found in the VoiceXML document, e.g. substring bounds error, or an undefined variable was referenced.

error.noauthorization

Thrown when the application tries to perform an operation that is not authorized by the platform. Examples would include dialing an invalid telephone number or one which the user is not allowed to call, attempting to access a protected database via a platform-specific