VoiceXML Async 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 (simple) dynamically generated VoiceXML documents or documents read from a database or other store (e.g., Directory Services).

The request is asynchronous.  That means the tool returns as soon as the VoiceXML session has been initiated (the initial document is loaded, the ownership of the interaction transferred to the VoiceXML session, and the interpreter is ready to start).  

The VoiceXML interpreter “owns” the interaction when the tool returns through the ‘Success’ exit.  The handler may not perform operations against the interaction unless it re-acquires the ownership (in which case the VoiceXML session aborts immediately).  

If the tool exits through the ‘Invalid Interaction’ or ‘Error’ exit, the handler remains 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 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 its 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

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.

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.

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 fails to load, an error.badfetch event with potentially additional decorations, such as  error.badfetch.http.404, is returned.  

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