ccxml elements - dialogprepare

CCXML 1.0-W3C Development Guide

<dialogprepare> element

The <dialogprepare> element is used to prepare a VoiceXML dialog, or audio resource for execution via the <dialogstart> element. While the usage of this element as a precursor to a dialog exection is entirely optional, best practices dictate that this is included in CCXML front-end applications that utilize VoiceXML content for finer-grained control. Of course, the dialog will execute in a thread that is entirely seperate execution thread, and will not block the execution of CCXML events that occur during the session.

When a dialog has been successfully readied for execution, a dialog.prepared event is thrown to the CCXML application. In the event that the dialog cannot be prepared for any reason, an error.dialog.notprepared event is sent to the CCXML session.

Be aware that if the prepareddialogid attribute is specified and a conferenceid attribute was specified on the prior <dialogprepare> element, specifying a different conferenceid on the <dialogstart> element will incur an error.dialog.notstarted event being thrown to the CCXML session.

usage

<dialogprepare conferenceid="(ECMAScript Expression)" connectionid="(ECMAScript Expression)" dialogid="(variable name)" enctype="(ECMAScript Expression)" hints="(ECMAScript Expression)" maxage="(ECMAScript Expression)" maxstale="(ECMAScript Expression)" mediadirection="(both/dialogtransmit/dialogreceive)" method="(GET|POST)" namelist="STRING" parameters="(variable name)" src="(ECMAScript Expression)" type="(application/voicexml+xml|audio/wav)">

attributes

conferenceid	Data Type: (ECMAScript Expression)	Default: Optional
	Unsupported Attribute The conferenceid attribute is used to define an ECMAScript identifier of a particular conference bridge. If neither the connectionid or conferenceid is defined, and the dialog had not previously been prepared, the interpreter will deafult to the 'id' indicated in the current event that is being processed. Note that if connectionid and conferenceid are both specified, an error.fetch event must be thrown.
connectionid	Data Type: (ECMAScript Expression)	Default: Optional
	The connectionid attribute is used within the context of the `<dialogprepare>` element as an ECMAScript expression that returns the identifier of a connection. It is required that the connection denoted in this attribute be associated with the dialog being prepared. Also note that either connectionid or confereceid may be specified, but not both.
dialogid	Data Type: (variable name)	Default: Optional
	The dialogid attribute is used to reference a predefined value that equates to the dialog identifier value for the dialog to be launched.
enctype	Data Type: (ECMAScript Expression)	Default: application/x-www-form-urlencoded
	enctype specifies an ECMAScript string expression that denotes the media encoding type of the submitted document, (when the POST method is used). The only allowable value of this attribute is 'application/x-www-form-urlencoded', which specifies that the indicates that the variables in the namelist attribute must be url-encoded.
hints	Data Type: (ECMAScript Expression)	Default: Optional
	The hints attribute can be used to specify information used by the platform to configure the event processor. The value of this attribute should equate to an object that contains an array property of "headers"; for instance: `<script> var Hints = new Object(); Hints.headers = new Object(); Hints.headers['x-mySipHeader'] = 'hello world'; </script>` Note that 'hints.headers' stores what headers to add to the sip request, and that only headers starting with an 'x-' prefix are sent.
maxage	Data Type: (ECMAScript Expression)	Default: Optional
	The maxage and maxstale attributes specify the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.
maxstale	Data Type: (ECMAScript Expression)	Default: Optional
	The maxage and maxstale attributes specify the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.
mediadirection	Data Type: (both/dialogtransmit/dialogreceive)	Default: Optional (both)
	Unsupported Attribute The mediadirection attribute specifies the media flow direction between the dialog and connection, (or conference) bothSpecifies a full duplex connection where the media flows in both directions. dialogtransmit: The dialog transmits media to the Connection or Conference but does not receive any media streams. dialogreceive:The dialog receives media from the Connection or Conference but does not transmit any media streams.
method	Data Type: (GET\|POST)	Default: Optional (GET)
	The method attribute specifies the HTTP method to use when sending the request. If unspecified, then the value of ‘GET’, (default) is assumed, unless the submission of multipart/form-data is encountered, in which case the implied method will be ‘POST’.
namelist	Data Type: STRING	Default: none - attribute is optional
	The namelist attribute denotes the space-separated list of variable names to be sent along with the fetch. The variables will then be available as a variable/value pair in the resultant URI querystring that is sent to the server.
parameters	Data Type: (variable name)	Default: none - attribute is optional
	The parameters attribute specifies a listing of whitespace delimited CCXML variable names which will be sent to the dialog target as a listing of variable/value pairs. Note that these values are formed by converting the referenced ECMAScript variable to string form.
src	Data Type: (ECMAScript Expression)	Default: none - attribute is required
	The src attribute indicates the URL of the VoiceXML dialog to be started. Also note that with the Voxeo dialog extensions, this can also be used to indicate playable audio files or dtmf tones to be output. In addition, this can also hold the value of a TTS string, and/or valid dtmf termdigit entries that can be accepted from the caller. Also allowed is a URI address specifying where a recorded audio stream is to be sent. See the 'Appendix D: Dialog Extensions' section for further details of this usage.
type	Data Type: (application/voicexml+xml\|audio/wav)	Default: application/voicexml+xml
	Specifies the MIME type of the requested resource to prepare. This value is used to determine and initiate the appropriate dialog system. Standard Values: application/voicexml+xml: Requests a VoiceXML interpreter instance. audio/wav: Requests a dialog system to play a simple audio prompt. Additional Voxeo-specific Extension Values: (see 'Appendix D' for additional details) application/x-texttospeech: Requests a dialog system to render a Text-To-Speech (TTS) prompt. application/x-recordaudio: Requests a dialog system to execute a simple audio recording dialog. application/x-fetchdigits: Requests a dialog system to execute a simple dialog to capture DTMF key-presses. application/x-senddtmf: Requests a dialog system to render DTMF tones.

parents

none

children

none

code samples

none

additional links

none

ANNOTATIONS: EXISTING POSTS

mheadd

12/7/2007 2:25 PM (EST)

What is the timeout value on <dialogprepare/>? In other words, how long will the platform wait in response to a request for a dialog before throwing a error.dialog.notprepared event?

Is there any way to explicitly set the timeout duration on <dialogprepare/>?

VoxeoDante

12/7/2007 4:18 PM (EST)

Hello,

There is no explicit timeout value for <Dialogprepare>. The dialogprepare will be effected by the platform level timeout value for fetches. The standard platform value for fetch timeouts is set to 10 seconds on Prophecy.

I do believe you can send a delay to the session to help modify the time if you would like. Something like so:

<send name="'timeout'" target="myDialogID" delay="'10s'" targettype="'dialog'" />

Please let me know if there are any followup questions.

Regards,
Dante Vitulano

amitsood

10/22/2008 10:31 AM (EDT)

If needed, Can we change the configuration value in the platform from 10 seconds to 4 seconds

voxeojeff

10/22/2008 10:45 AM (EDT)

Hi Amit,

Unfortunately, in our shared hosted environment, such modifications are not possible, considering it would require changes to the config file, which may affect other customers. This should be possible on a local installation of prophecy, though.

Hope this helps,
Jeff