CCXML 1.0-W3C Development Guide Home  |  Frameset Home

<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="(ECMAScript Expression)">


attributes

conferenceid Data Type: (ECMAScript Expression) Default: Optional
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.

If specified, the dialog being started MUST be joined to the referenced conference as specified by the <mediadirection> attribute.

You should call <createconference> within the same session used to start the dialog for the conference.

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 indicates that the variables in the namelist attribute must be url-encoded.

Note: The enctype attribute should not be used in conjunction with the prepareddialogid attribute.
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" as shown in the following example:

<script>
  var Hints = new Object();
  Hints.headers = new Object();
  Hints.headers['x-mySipHeader'] = 'hello world';
</script>

Note: The 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.

Note: The maxage attribute should not be used in conjunction with the prepareddialogid attribute.
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)
The mediadirection attribute specifies the media flow direction between the dialog and connection, or conference.
  • both: Specifies 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.

The bridge does not take place until a subsequent <dialogstart> is executed, but this attribute may be provided as guidance to the dialog environment for preparation. If no value is specified, the dialog environment must make no assumptions as to the bridging type.

The mediadirection must match in both the dialogprepare and dialogstart elements.

If no value for the mediadirection attribute was specified on the previous <dialogprepare> element, any <mediadirection> type option may be specified.

Note: The mediadirection attribute should not be used in conjunction with the prepareddialogid attribute.
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’.

Note: The method attribute should not be used in conjunction with the prepareddialogid attribute.
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.

Note: The parameters attribute should not be used in conjunction with the prepareddialogid attribute.
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.

Note: You must escape reserved URI characters such as the & and # signs.

NOTE: The src attribute should not be used in conjunction with the prepareddialogid attribute.
type Data Type: (ECMAScript Expression) Default: application/voicexml+xml
Specifies the MIME type of the requested resource.  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.
  • application/x-callxml: Requests a dialog system to start a CallXML dialog.
  • application/x-transfer: Initiates a transfer to a new call destination specified in a script.

NOTE: The type attribute should not be used in conjunction with the prepareddialogid attribute.



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
macaulayahmed
11/19/2010 4:29 AM (EST)
Is it possible to point <dialogprepare/> to a URI which is a server side to generate the resulting ccxml/vxml content.
voxeoJeffK
11/19/2010 4:52 AM (EST)
Hello,

Yes, certainly. This is common. The dynamic script must simply return valid XML.

Regards,
Jeff Kustermann
Voxeo Support
SSA_Whispir
12/21/2010 10:54 PM (EST)
Hi guys,

Does the <dialogprepare> tag prepare any prefetch'ed <audio> tags from the VXML dialog as well (i.e. those with fetchhint="prefetch")?

P.S. The scenario is: an outbound call is made to a CCXML app, the app prepares a VXML dialog, then the app creates a call and starts the dialog. However, the VXML plays some audio file as its first prompt. We'd like to 'pre-fetch' this audio somehow before the VXML dialog is started (since it is the first prompt of the VXML)
voxeoJeffK
12/22/2010 4:37 AM (EST)
Hello,

Yes <dialogprepare> will cause prefetch of the dialog file and its included resources up to the first input item. Prefetching stops at the first input item since its assumed that user input will then influence what resources/data are further needed for execution.

Regards,
Jeff Kustermann
Voxeo Support
romilly1
12/22/2010 5:38 PM (EST)
You said: "Prefetching stops at the first input item since its assumed that user input will then influence what resources/data are further needed for execution."

Does that mean it will also execute any <data> tags before the first user input? (i.e. data tags for simple http requests to a web server)
voxeoJeffK
12/23/2010 1:11 AM (EST)
Hello,

Yes, a <data> fetch is certainly possible during the pre-fetching. Commonly this can be avoided by simply including a "dummy" field in a form before the <data> so that prefetching stops where desired. For example:

[code]
  <form id="fetchStopper">
    <field name="dummy">
      <property name="timeout" value="10ms"/>
      <!-- set the noinput timeout very low -->

      <!-- create a 'garbage' grammar that will never, EVER get a match -->
      <grammar> [Supercalifragilisticexpialidocious] </grammar>

      <filled>
        <prompt> no way this will ever happen </prompt>
      </filled>

      <noinput>
        <goto next="#realForm"/>
      </noinput>
    </field>
  </form>

  <form id="realForm">
...
[/code]

Regards,
Jeff Kustermann
Voxeo Support
 
puneetb
2/7/2011 4:13 PM (EST)
I do not understand the real benefit of this tag (dialogprepare). Does it reduce delay by means of prefetching? At what stage in my CCXML should I use this tag? Can you please post an example that shows the usage and benefit of this tag?

Thank you.
PB
voxeoJeffK
2/8/2011 4:06 AM (EST)
Hello,

Yes, prefetching is a benefit, but really the benefit is to be able to gracefully handle a problem with the dialog. If there is a problem you get a error.dialog.notprepared event, and can then perhaps try to execute a failover dialog instead.

regards,
Jeff Kustermann
Voxeo Support
SSA_Whispir
8/22/2011 12:33 AM (EDT)
The following sentence under the description of the 'enctype' attribute does not make sense:
...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.
voxeoJeffK
8/22/2011 11:46 AM (EDT)
Hello,

Thank you. I've noted this to our documentation team for clarification.

Regards,
Jeff Kustermann
Voxeo Corporation

login


© 2012 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site