<bevocal:listen>

Extension. Allows the application to suspend execution and listen to the user during an outbound call.

Syntax

 <bevocal:listen
     name="string"
     expr="js_expression"
     cond="js_expression"
 >
   Optional Content
 </bevocal:listen>

Description

To use this tag, the containing <vxml> tag must declare the XML namespace bevocal by including the following attribute:

 xmlns:bevocal="http://www.bevocal.com/"

A <bevocal:listen> element lets the application listen to the user during an active outbound call that was initiated by a <bevocal:dial> tag. During execution of the <bevocal:listen> element, the user and the called third party talk to each other. The application is quiet. No universal grammars or grammars in higher scopes are active. The application ignores all speech and DTMF signals from the called third party.

If the <bevocal:listen> element includes any child grammars, the application listens to the user. If a user utterance matches a child grammar, the <bevocal:listen> tag's input variable is set to the recognition result. The bevocal.hotwordmin and bevocal.hotwordmax properties specify the minimum and maximum time duration, respectively, for an utterance that can match a <bevocal:listen> grammar.

If a user utterance matches a child grammar, any child <filled> elements are executed in the order in which they occur. Recognition does not cause the call to terminate. If desired, a <filled> element can disconnect the call explicitly:

Following execution of the <bevocal:listen> element, the interpreter proceeds as usual, searching for the next form item to execute.

Note: This and other call-control tags constitute a BeVocal VoiceXML extension. Committees are currently working to standardize call-control features for VoiceXML; however, the approval of call-control standards will take some time. BeVocal VoiceXML contains this extension to allow developers to take advantage of call-control features before standards are available, even though the eventual standards are likely to be nothing like the current extension. When the features in the BeVocal VoiceXML extension become a part of VoiceXML or a separate call-control standard, BeVocal VoiceXML will implement the standard. We will then deprecate the current extension and provide developers with information on how to upgrade their applications to the new standard.

Attribute	Description
name	Name of the input variable that will hold the recognition result. The variable name may not be a JavaScript reserved keyword. The input variable has dialog (form) scope; its name must be unique among all VoiceXML and JavaScript variables within the form's scope.
expr	JavaScript expression that assigns the initial value of the input variable for this field. Optional (default is undefined). If you set the input variable to a value other than undefined, you'll need to clear it before this element can execute.
cond	JavaScript boolean expression that also must evaluate to true for this element to execute. Optional (default is true). If not specified, the value of the input variable alone determines whether or not this element can execute.

The following events may be thrown by the execution of a <bevocal:listen> element:

Event	Description
connection.disconnect.hangup	The user hung up. New in VoiceXML 2.0.
telephone.disconnect.hangup	The user hung up. VoiceXML 1.0 only.
connection.far_end.disconnect	The called third party hung.
connection.far_end.disconnect.timeout	The outbound call was terminated due to timeout.
error.semantic	No outbound call is active.

Properties of the Shadow Variable

Corresponding to the input variable name is a "shadow variable" called name$. After the input variable is filled, some additional information is available in the following properties of this shadow variable:

Property	Description
confidence	The recognition confidence level (with 0.0 representing the lowest confidence and 1.0 representing the highest).
utterance	A string representation of the words actually spoken by the user.
inputmode	The mode in which input was provided, one of voice or dtmf.
duration	After the transfer is complete, the floating point duration of the call in milliseconds.

For a field whose name is name, you access the property propName of the shadow variable with the syntax:

 name$.propName

For example, you access the duration property for a field named services field as:

 services$.duration

	Tip:
	•  If a JavaScript expression contains any of the characters "<", ">", or "&", that character must be replaced with the corresponding escape sequence "&lt;", "&gt;", or "&amp;". For more information, see JavaScript Quick Reference.

Usage

Parents	Children
<form>	<catch> <error> <filled> <grammar> <help> <noinput> <nomatch> <property>

See Also

Café Home | Developer Agreement | Privacy Policy | Site Map | Terms & Conditions Part No. 520-0001-02 | © 1999-2007, BeVocal, Inc. All rights reserved | 1.877.33.VOCAL