Event Handling

The VoiceXML interpreter throws events for many different situations: application errors, user does not respond, etc. VoiceXML defines a set of elements to catch common events thrown by the interpreter: <catch>, <error>, <help>, <noinput>, and <nomatch>. An element inherits the catch elements from each of its ancestor elements, as needed. For example, if a <field> element does not contain a <nomatch > element, but its parent <form> does, the form’s nomatch element is used. In this way, common event handling behavior can be specified at any level, and it applies to all descendents.

Events Reference

General VoiceXML Events

Click here for details on the _message variable, which may provide details about the cause of an event when it has been caught.

Event

Description

cancel

The user has requested to cancel playing of the current prompt. (Available when the universals property includes cancel)

exit

The user has asked to exit. (Available when the universals property includes exit)

help

The user has asked for help. (Available when the universals property includes 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 property maxspeechtimeout.

telephone.disconnect.hangup †

Caller hangs up. Applies at any time except during blind transfers. (See more detailed documentation and special behaviour)

Note: This event has an associated anonymous variable.

telephone.disconnect.transfer †

Call was "blind transferred" to another line and will not return. (Note limitation)


†Note: See Call-Related Events for details on the naming conventions.

Errors

Click here for details on the _message variable, which may provide details about the cause of an error when it has been caught.

Error

Description

Default Message

error

Any error occurred.

Sorry, there has been an error.

error.application
(extension)

Any miscellaneous application error occurred.

There is an error in the application. Goodbye.

error.asr
(extension)

Any ASR error occurred.

A speech recognition error has been detected. Goodbye.

error.asr.exceedlicense 
(extension)

The ASR license for the platform was exceeded.

Sorry, you have exceeded your ASR license. Goodbye.

error.asr.noresource 
(extension)

No ASR resource was available.

error.noresource.asr.

Sorry, there is no ASR resource available. Goodbye.

error.asr.unknownengine 
(extension)

The specified ASR engine is unknown.

The specified ASR engine is unknown. Goodbye.

error.badfetch

A fetch of a resource failed and the interpreter context reached a place in the document interpretation where the fetch result was required.

Note: When a page makes a transition to a page in which there are invalid elements/attributes or where elements are in invalid scopes, an error.badfetch event should be thrown in the calling page. However, the Dialogic(r) IP Media Server currently just logs a parse warning and continues with compilation/execution of the new page (no error is thrown).

The requested page cannot be found. Goodbye.

error.badfetch.http.<response code>

A fetch of a resource failed and the interpreter context reached a place in the document interpretation where the fetch result was required. The interpreter context returned the specific HTTP response code.

None

error.badfetch.https.<response code>

A fetch of a resource failed and the interpreter context reached a place in the document interpretation where the fetch result was required. The interpreter context returned the specific HTTPS response code.

None

error.badfetch.<protocol>.<response code>

A fetch of a resource failed and the interpreter context reached a place in the document interpretation where the fetch result was required. The interpreter context returned the specific protocol and response code.

None

error.connection.noauthorization
error.telephone.noauthorization †

The caller is not allowed to call the destination, during a <transfer>. There may be additional factors that signify noauthorization. Note: During a <call>, this case will result in the call variable being set to "restricted_phone_no" or a com.voicegenie.call.failed event being thrown. Applies to both blind and bridge transfers.

None

error.connection.baddestination
error.telephone.baddestination †

The destination URI is malformed, during a <transfer>. Note: During a <call>, this case will result in the call variable being set to "invalid_phone_no" or a com.voicegenie.call.failed event being thrown. Applies to both blind and bridge transfers.

None

error.connection.nolicense
error.telephone.nolicense 
(extension)

The platform could not establish the outbound call due to a lack of licenses. Applies to both blind and bridge transfers.

For example, this error will be thrown if a transfer is requested but the number of calls in progress has already reached the limit in the Dialogic license.

None

error.connection.noresource
error.telephone.noresource †

The platform could not allocate resources to place the call, during a <transfer>. Note: During a <call>, this case will result in the call variable being set to "noresource" or a com.voicegenie.call.failed event being thrown. Applies to both blind and bridge transfers.

None

error.connection.noroute
error.telephone.noroute †

The platform was not able to route the call to the destination, where the destination URI has the correct format. Applies to both blind and bridge transfers.

 

None

error.connection.<protocol>.<nnn>

An error occurred that does not correspond to one of the other error.connection events. The keyword protocol is the name of the protocol. The keyword nnn is the failing reason. For example, error.connection.isdn.glare. Applies only to bridge transfers. Not currently supported.

None

error.grammar.asr 
(extension)

An error was found in a speech grammar.

There is an error in the speech grammar. Goodbye.

error.grammar.dtmf
(extension)

A error was found in a DTMF grammar.

There is an error in the DTMF grammar. Goodbye.

error.internal
(extension)

An internal VoiceGenie server error occurred.

Sorry, there has been an internal error. Goodbye.

error.noauthorization

The user is not authorized to perform the requested operation.

The requested operation is not authorized. Goodbye.

error.noresource.asr 
(extension)

No ASR resource was available.

Sorry, there is no ASR resource available. Goodbye.

error.noresource.tts 
(extension)

There was no TTS resource available, when attempting to play TTS.

Sorry, there is no TTS resource available at this moment. Please try again later. Goodbye.

error.script
(extension)

An error was found in ECMAScript.

This error is no longer used. An error.semantic is thrown in this case, instead.

There is an error in the application. Goodbye.

error.semantic

A run-time error was found in the VoiceXML document.

There is a semantic error in the application. Goodbye.

error.tts
(extension)

Any TTS error occurred.

A TTS error has been detected. Goodbye.

error.tts.badcapability 
(extension)

The TTS engine does not support the requested TTS capability, such as language. (Not used in current VoiceGenie version).

Sorry, the specified TTS capability is not supported now. Goodbye.

error.tts.badtext
(extension)

An error was found in the text to be played as TTS.

A bad text TTS error has been detected. Goodbye.

error.tts.noresource 
(extension)

There was no TTS resource available, when attempting to play TTS.

This error was renamed error.noresource.tts.

Sorry, there is no TTS resource available at this moment. Please try again later. Goodbye.

error.tts.unknownengine 
(extension)

The property TTSENGINE did not match engine name configured in the platform, when attempting to play TTS.

Sorry, unknown TTS engine is specified. Goodbye.

error.unsupported.element

An element was found that is not supported by the platform.

Element not currently supported. Goodbye.

error.unsupported.format

The requested resource has a format that is not supported by the platform.

Format not currently supported. Goodbye.

error.unsupported.language

The platform does not support the language for either speech synthesis or speech recognition.

Language not currently supported. Goodbye.

error.unsupported.objectname

The requested object is not supported. Note that 'objectname' is a fixed string; it is not substituted with the name of the object.

Object not currently supported. Goodbye.

error.unsupported.transfer.consultation

The platform does not support the requested transfer, when type="consultation" (or bridge="false"/type="supervised").

None

error.unsupported.transfer.blind

The platform does not support blind transfers. Applies only to blind transfers. Note that this event is only supported in a PSTN environment, not SIP.

None

error.unsupported.transfer.bridge

The platform does not support bridge transfers. Applies only to bridge transfers.

None

error.unsupported.uri*

The platform does not support the URI format (ex. fax://...). The special variable _message will contain the string "The URI x is not a supported URI format", where x is the value of the dest or destexpr attribute of the transfer. Applies to both blind and bridge transfers.

None


†Note: See Call-Related Events for details on the naming conventions.

 

Default Catch Elements

The interpreter provides the following default event handlers:

Event Handler

Audio Provided

Action

<catch event="cancel">

no

don't reprompt

<error>

yes (see chart above)

exit interpreter

<catch event="exit">

no

exit interpreter

<help>

yes (<silent audio>)

reprompt

<noinput>

no

reprompt

<nomatch>

Note: This will also be the default handler for nomatch.serverdown*.

yes ("I do not understand.")

reprompt

<catch event="maxspeechtimeout">

yes ("I do not understand.")

reprompt

<catch event="connection.disconnect
      telephone.disconnect">

Note: This will be the default handler for
telephone.disconnect.hangup, and
telephone.disconnect.transfer. †

(more detailed documentation...)

no

exit interpreter

<catch event="com.voicegenie.call
      com.voicegenie.message">

no

don't reprompt

VoiceGenie additionally provides default handlers of the format:

<catch event="other_event">,

for each of the other_events listed in the error chart above with a "Default Message". Events in the chart with no default message will be caught by a less specific default event handler, and the default message for the less specific event will be played.

For example, the handler <catch event="error.unsupported.uri"> is not defined by default, so error.unsupported.uri will be caught by <error>, which plays "Sorry, there has been an error."

yes (see chart above)

exit interpreter


†Note: See Call-Related Events for details on the naming conventions.

Note: Some user-defined events that are thrown by the application can still be caught by one of the default handlers, based on the rules for selecting an event handler. For example, if an application throws nomatch.invalidpin, it will be caught by the default <nomatch> handler if no other handler is defined. If the application throws a user-defined event that is not caught by one of the default handlers, the application must define a handler for that event, or the call will be terminated immediately. In the case that no handler is defined, a platform error (exec_error or parse_error) will be logged; no further VoiceXML-level error processing will be possible to allow for graceful termination.