Properties

The main body of a VoiceXML document will often begin by declaring and initializing each property used in the file. A property customizes the behavior of NVP. For example, properties control how the interpreter behaves when prompting the user for input, recognizing speech or DTMF input, and fetching documents and other resources.

A property is declared using the <property> element. For example, the pizza.vxml file main body begins with several declarations of properties:

<property name="speedvsaccuracy" value="1.0"/>
<property name="maxspeechtimeout" value="10s"/>
<property name="timeout" value="8s"/>
<property name="confidencelevel" value=".50"/>

Properties can be set at different levels, which determine when and how the specified value applies.

Types of properties

VoiceXML properties can be grouped into several general categories:

  • Speech recognition: Affects how NVP interprets caller speech. For example, the confidencelevel property determines how closely a caller utterance must match a pattern in the database before it will be accepted as a possible match.

  • DTMF: Applies to DTMF input from the keypad. For example, the interdigittimeout property defines the maximum time allowed between each DTMF tone entered (how long the caller has between pressing one keypad button and the next).

  • Prompt and collect: Affects how a prompt is played. For example, the timeout property determines how long NVP will wait for user input after a prompt before it throws an error or event.

  • Resource fetching: Determines whether and how information is requested from the server. For example, the audiomaxage property determines the maximum allowable age of any cached audio file.

  • Grammar and natural language: Affects grammar use. For example, the universals property specifies the built-in universal commands available.

  • Miscellaneous: Properties that do not fit into another category.

For more information, see VoiceXML elements.

Property precedence

Property values can be specified at different levels of an application:

  • In the root document

  • In other VoiceXML documents (or subdocuments, such as a context file)

  • Within a form or menu in a document

  • In an individual form item within a form

  • In a grammar invoked anywhere within a VoiceXML document

The value specified for a property applies for the level at which it’s specified, and all lower levels that descend from it. However, a property specified at a lower level temporarily overrides a property value inherited from a higher level.

For example, consider the timeout property. This property instructs the voice browser service how long to wait for a response after each prompt. If the caller doesn’t respond within that time, the voice browser service throws an event (a system warning) and goes to the next instruction. For example, suppose you set a timeout of eight seconds in your application’s root document:

<property name="timeout" value"8s">

This sets a default timeout value of eight seconds throughout your application. However, you can override it by setting a different timeout within a form. For example, suppose that an application subdocument includes the following:

<form id="timeout_example">
  <property name="timeout" value="10s"/>
  <field id="vary_timeout" type="digits">
    <prompt>
      You have ten seconds to answer this prompt.
    </prompt>
  </field>
  <field name="confirmation" type="boolean">
    <property name="timeout" value="5s">
    <prompt>
      But you only have five seconds to answer this prompt.
    </prompt>
  </field>
</form>

In this example, the default timeout value for all items in the timeout_example form is ten seconds, as set in the property element that appears immediately after the form declaration. This value overrides the earlier default of eight seconds that has been inherited from the root application.

However, the field within the form sets a timeout value of only five seconds, which applies for that field only. All other fields in the form use the ten second default, while other forms in the document use the eight second default.

Service properties

The behavior of NVP can also be affected by a service property. A service property is a property that applies directly to an NVP service (for example, the Speech Server) rather than to a single VoiceXML application. This means that it applies the same behavior for every application that uses that particular instance of the service.

The majority of service properties can be set only in the Management Station. However, a select few may be set in an application by using a <property> element.

Context files

You can set properties within <property> elements in any VoiceXML document in your application. However, this means that if you want to change a property in the course of application tuning, you must locate it in the appropriate VoiceXML document and change it there. This can be a cumbersome process if your application is large and you have many properties to modify.

As an alternative, you can define all properties in a context file. A context file is an XML file that you can import into a VoiceXML document to specify exactly which value should be used for each property at each point in the application.

For example, this context file sets timeout values for the “vary_timeout” and “confirmation” fields from our previous example:

<?xml version="1.0"?>
<context>
document-level default properties
  <context>
    <context id="vary_timeout">
    <property name="timeout" value="10s"/>
    </context>
    <context id="confirmation">
    <property name="timeout" value="5s"/>
    </context>
  </context>
</context>

The advantage of this approach is that it puts all properties in a single file, so it’s more convenient to locate and modify each property.

Not all properties are appropriate for use in a context file. Check the property descriptions in VoiceXML properties to determine whether a given property can appear in a context file.

For a full discussion of context files, see Using context files.