# 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 forms 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
- Errors
- Default Catch Elements

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.