Invoking a VoiceXML application

A VoiceXML Version 2.0 application is normally invoked on a connection that is in the CONNECTED state. If the underlying telephony connection allows it, a VoiceXML application can be invoked in the ALERTING state.

In dialog environments where dialogs can take a significant length of time to initialize, particularly when documents are stored on a remote server accessed over a network, you can preload a VoiceXML Version 2.0 application by using a <dialogprepare> element

Whether it is being started immediately or prepared for use, to invoke a VoiceXML 2.0 application, you need to set the type attribute to "'application/xml+vxml'"

To preload a VoiceXML application, your CCXML document must use a <dialogprepare> element within a <transition> element: 
<transition event="connection.alerting" name="evt">
	<dialogprepare src="'http://www.example.com/welcome.vxml'" type="'application/xml+vxml'"
       connectionid="evt.connectionid"/>
</transition>

When using <dialogprepare>, a connectionid can be provided, but this can be overridden if desired in the subsequent <dialogstart> element. The preloaded dialog can be referenced by the subsequent <dialogstart> element by using the prepareddialogid attribute.

To invoke a VoiceXML application, your CCXML document must use a <dialogstart> element within a <transition> element: 
<transition event="connection.connected" name="evt">
	<dialogstart src="'welcome.vxml'" type="'application/xml+vxml'" connectionid="evt.connectionid"/>
</transition>

Optionally, your CCXML application can specify data to be passed to the VoiceXML application in one of two ways:

Passing data with the namelist attribute

In the following example, a .jsp file is being used to return VoiceXML dynamically. The namelist attribute is used to send parameters to a web server. The document on the web server than has access to these parameters. For example a .jsp file which then modifies then rendered VoiceXML according to the passed parameters.

<transition event="connection.connected" name="evt">
	<dialogstart src="'http://www.example.com/welcome.vxml'" type="'application/xml+vxml'"
		namelist="Field1 Field2" connectionid="evt.connectionid" />
</transition>

where Field1 and Field2 are the names of previously declared and initialized CCXML variables.

The namelist variables are appended to the src URI as a parameter sequence. A '?' is appended if it does not already exist. It is up to the web server to process the data on the fetch and, for example, generate a dynamic document page that is sent to the VoiceXML browser. In the above example, if Field1 and Field2 had values of Val1 and Val2, respectively, the following URI would be generated: 
http://www.example.com/welcome.vxml?Field1=Val1&Field2=Val2
Note: URIs that include numeric IPv6 format addresses, must have the numeric part within [ ] brackets, for example: 
http://[2002:914:fc12:195:0000:8a2e:0370:7334]/welcome.vxml
This applies to all protocols.

Passing data with the parameters attribute

The parameters attribute contains a list of one or more whitespace separated CCXML variable names. These variables are sent to the dialog environment as a list of name/value pairs. Names are sent exactly as they are specified and values are formed by converting the referenced ECMAScript variable to string form (which is undefined for objects). The dialog environment determines how passed parameters will be handled

In the following example, a static VoiceXML document welcome.vxml is being launched. The values specified in the parameters attribute of the <dialogprepare> and <dialogstart> elements are created as local session variables within the scope of the document. The names and values specified in the parameters attribute are stored in the session.connection.ccxml.values array and also in the session.ibm.values array. The latter is reserved for ‘platform-specific’ use.

<transition event="connection.connected" name="evt">
	<dialogstart src="'http://www.example.com/welcome.vxml'" type="'application/xml+vxml'"
		parameters="para1 para2" connectionid="evt.connectionid" />
</transition>

where para1 and para2 are the names of previously declared and initialized CCXML variables.

The values of the parameters can be accessed in the VoiceXML document through the corresponding session variables, in this example as session.connection.ccxml.values.para1 and session.connection.ccxml.values.para2. 
<?xml version="1.0" encoding="iso-8859-1"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml" xml:lang="en-US">
 <form id="LogCalls">
  <block>
<!-- Obtaining a unique Call ID and the destination department from CCXML -->
   <var name="callid" expr="session.connection.ccxml.values.para1"/>
   <var name="dept" expr="session.connection.ccxml.values.para2"/>
      <log>Unique Call ID is: <value expr="callid" />
           Destination department is: <value expr="dept" />
      </log>
<!-- Submit unique Call ID and the destination department to servlet -->
   <submit namelist="callid dept"
           next="http://SupportLine.com/servlet/MonitorCall"/>
  </block>
 </form>
</vxml>
Note: URIs that include numeric IPv6 format addresses, must have the numeric part within [ ] brackets, for example: 
http://[2002:914:fc12:195:0000:8a2e:0370:7334]/welcome.vxml
This applies to all protocols.
Parent topic: CCXML Programming