When using CCXML to start a VoiceXML dialog using a dialogstart you may want to pass information to that dialog, such as data sent on SIP headers from the call or internal data that lets you use the same VoiceXML to do different things at different stages of the application. You might supply those values to the namelist attribute to send them on an HTTP request to a JSP or other server side script, but there is a method that doesn't involve the need for such scripting.
The <dialogstart> attribute "parameters" lets you specify a list of variables that you want to make available to the VoiceXML application. These values will then be populated into properties of the session.connection.ccxml.values object in VoiceXML using the variable names supplied. Let's look at an example where we want to use VoiceXML to play out some DTMF tones to the call:
In CCXML:
<transition event="connection.connected">
<!-- This assumes a script has defined this function and the variable aai has been set by a previous part of the document -->
<var name="DTMF" expr="getDTMFFromAAI(aai)"/>
<dialogstart src="'play_out_dtmf.vxml'" parameters="DTMF" />
</transition>
play_out_dtmf.vxml:
<?xml version="1.0" encoding="iso-8859-1"?>
<vxml xmlns="http://www.w3.org/2001/vxml" version="2.1" xml:lang="en-US">
<script>
var dtmfs = '1234';
if (session.connection.ccxml != null) {
if (session.connection.ccxml.values != null) {
if (session.connection.ccxml.values.DTMF != null) {
dtmfs = session.connection.ccxml.values.DTMF;
}
}
}
</script>
<form>
<block>
<prompt>
<audio src="silence_250.wav"/>
<value mode="dtmfplay" expr="dtmfs"/>
<audio src="silence_250.wav"/>
</prompt>
<log expr="'DTMFs played out were ' + dtmfs"/>
</block>
</form>
</vxml>
Note that good practise is to check if the ccxml and values objects exist before trying to access the parameters stored there, otherwise your application will get an error.semantic event and fall over when started without being supplied any parameters or when started independently of CCXML.
By default, if a VoiceXML document is stated using a dialogstart, BVR will send an HTTP HEAD request to ensure that the resource exists. This allows BVR to determine early on whether or not the dialog start will be successful.
In some situations this behaviour may not be desirable, for example when using dynamically generated VoiceXML, or if the server hosting the VoiceXML does not handle this request properly.
Setting this hint to true prevents the sending of the HTTP HEAD request which is used to determine if a VXML document exists before fetching it.
Example:
<var name="hints" expr="new Object()"/>
<assign name="hints.skip_http_head" expr="'true'"/>
<dialogstart src="'http://my.web.server/start.vxml'" type="'application/xml+vxml'" connectionid="evt.connectionid" hints="hints"/>
Specify the fetch timeout for this VXML session. Overrides the fetch_timeout parameter from bvr.config for just this dialog. Note that this affects everything fetched in the VXML session (e.g. audio), not just the VXML documents themselves.
The value for this field is a human readable time, e.g. "12 seconds"
Example:
<var name="hints" expr="new Object()"/>
<assign name="hints.fetch_timeout" expr="'10 seconds'"/>
<dialogstart src="'http://my.web.server/start.vxml'" type="'application/xml+vxml'" connectionid="evt.connectionid" hints="hints"/>