VoiceXML Initiate Document

This VoiceXML tool sends a request to the VoiceXML Interpreter to initiate a session with the specified interaction, and the initial VoiceXML document is given as an argument. This tool is most useful to interpret dynamically generated VoiceXML documents or documents read from a database. This tool issues a synchronous request, which means the tool will block other events until the VoiceXML session completes.

If the tool returns through any exit other than Disconnected, Transferred, or Lost Ownership, the handler will (again) be the owner of the interaction.

Inputs

Interaction

The unique interaction identifier (e.g., CallID) to send to the VoiceXML interpreter.

Document

This is an XML DOM node of the VoiceXML document to interpret.  The argument may either be the document node or the <vxml> element.

Queued Plays Processing

Note:  This parameter is not currently enabled but it is defined for future use.

This optional parameter specifies how to process pending prompt plays.  There are three options:  

0	Default. - Play as "fetchaudio."  Let the current prompts play until the VoiceXML session has started.  Then abort the current prompt as soon as the VoiceXML session is ready to play its own prompts.
1	Play to Completion. - Play the current prompt until it finishes, even if the VoiceXML session is started and ready to play it's own prompts.
2	Abort. - The VoiceXML interpreter aborts any pending prompts immediately when it gets the call ownership.  The Interpreter uses any global “fetchaudio” settings during the fetch.  If the “fetchaudio” property has no value (default), nothing is played (silence).

Argument Names

An optional string list of argument name-value pairs that are passed to the interpreter as arguments.

Argument Values

An optional string list of argument values (name/value pairs) that correspond to the Argument Names. These arguments are available in VoiceXML through 'session.name' or just simply 'name.'  

Force Interaction Ownership

This checkbox explicitly tells the VoiceXML interpreter to force the interaction ownership.

Unchecked	Default.  The VoiceXML interpreter only acquires ownership if the handler currently owns the interaction.
Checked	The VoiceXML interpreter always acquires the interaction ownership.

Outputs

Return Value

This string is the result of the ‘expr’ expression of the <exit> element.  Empty string if no return value.

Result Data

This XMLNode is an element of the result data of the session.  (“namelist” argument of the <exit> element).  It is a NULL node if there is no result data.  

Event Name

This string is the VoiceXML event that caused the interpreter to exit, or the reason for a session initiation failure.  

It is an empty string if the session terminated through the <exit> element.

Event Message

This string is additional message text associated with the VoiceXML event (‘_message’ property).

Exit Paths

Success

The VoiceXML session completed successfully and the return value and/or result data (XML node) are valid.

Disconnected

The interaction disconnected during the session.

Transferred

The interaction was transferred to another destination during the session through the <transfer> element.

Lost Ownership

Some other entity has taken away the ownership of the interaction during the VoiceXML session.

Invalid Interaction

The interaction type is not supported by the VoiceXML interpreter.

Unhandled Event

This exit path is taken if the session terminated because some event other than “error” is thrown during the session and not handled by the VoiceXML application.  

The ‘Event Name’ output parameter contains the name of the event and ‘Event Message’ may contain additional information.

Failure

An error occurred.  That usually means an “error” event was thrown but not caught in the VoiceXML document.  The name of the event is returned in ‘Event Name.’  If the initial document is not a valid VoiceXML document, an “error.badfetch” event will be returned.  

The ‘Event Message’ parameter usually contains additional information about what went wrong.