CCXML 1.0-W3C Development Guide Home  |  Frameset Home

<dialogstart>  element


The <dialogstart> element is used to launch a VXML dialog and associate it with a specific call leg. Said dialog executes on an entirely separate thread of execution from the invoking CCXML document, leaving the CCXML script in control to handle incoming events.

If, for any reason, the dialog cannot be started, an 'error.dialog.notstarted' error event is thrown. When the dialog completes, a 'dialog.exit' event is returned to the event queue of the invoking CCXML document. Note that telephony variables, (ANI, DNIS) will be propagated from the call leg to the dialog application. Note that whenever the full string passed down to through the <dialogstart> exceeds 500 characters, the method will inherently be switched to POST.




usage

<dialogstart 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)" prepareddialogid="(ECMAScript Expression)" 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. If this value, and the conferenceid value is left unspecified, then the CCXML interpreter will use the id value of the current event being processed. Also note that either connectionid or confereceid may be specified, but not both.

dialogid Data Type: (variable name) Default: none - attribute is optional
The dialogid attribute specifies the value of the session name used to identify the launched dialog. This value is used to reference dialog events, and is used as an identifier when the <dialogterminate> element is invoked.

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
This attribute indicates the space-separated list of variable names to be appended to the dialog URL as parameters. The variables will then be available as a variable/value pair in the resultant URI querystring that is sent to the server.

NOTE: The namelist attribute should not be used in conjunction with the prepareddialogid attribute.
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.
prepareddialogid Data Type: (ECMAScript Expression) Default: Optional
The prepredialogid attribute is used to specify an ECMAScript expression that evaluates to the dialog identifier that has been readied by way of the <dialogprepare> element. In the event that the identifier refers to an invalid dialog, or one that has already executed, then an error.dialogwrongstate event will be thrown. This attribute must not be specified in conjunction with the src, type, enctype, mediadirection, maxage, method, parameters, or namelist attributes otherwise, unexpected results such as variables not being passed to the target dialog may occur.
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

<1.0 dialogstart - src-type> sample
<ccxml version="1.0">

  <var name="initState" expr="'state_1'"/>
  <var name="MyCallID"/>

  <eventprocessor statevariable="initState">

    <transition event="connection.alerting" state="state_1">
      <assign name="MyCallID" expr="event$.connectionid"/>
      <send name="'MyEvent'" target="session.id"/> 
    </transition>

    <transition event="MyEvent">
        <accept connectionid="MyCallID"/>     
    </transition>

    <transition event="connection.connected" state="state_1">
      <log expr="'***** CALL WAS ANSWERED *****'"/>
      <dialogstart src="'dialog.vxml'" type="'application/voicexml+xml'"/>
    </transition>
   

    <transition event="error.dialog.notstarted" state="state_1">
        <log expr="'****** ERROR.DIALOGNOTSTARTED.NAME = ' + event$.name"/>
    </transition>


    <transition event="dialog.exit">
      <log expr="'***** CALL EXITING *****'"/>
      <exit/>
    </transition>

  </eventprocessor>
</ccxml>


<:dialog.vxml>
<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1">

  <form id="F1">
    <block>
    <prompt>
      Welcome to my voice X M L dialog.
      Goodbye
    </prompt>
    </block>
  </form>
</vxml>



additional links

W3C Specification


  ANNOTATIONS: EXISTING POSTS
bpcamac
1/2/2009 1:57 AM (EST)
I have an application which needs to play an announcement to all participants of a running conference.  I was going to use the dialogstart with conferenceid parameter but notice it isn't supported on the Voxeo platform :(

One workaround that I've experimented with is unjoining all the callLegs, and then starting the dialog on each callLeg as they become available, then waiting for the dialog.exit, then rejoining each to the conference.  Although it works in principle, in practice its not very smooth and I fear it may not be scalable.

Is there some way to start a dialog on these callLegs without breaking them away from the conference?

Alternatively, would Voxeo be interested in implementing this feature?

cheers,
Brenton
voxeoAlexBring
1/2/2009 5:18 AM (EST)
Hello Brenton,
    As it is we do not have an estimated time as to when this feature may be included into the Prophecy Platform. Our Platform Engineers are working to include this feature, but as mentioned there is no ETA at the moment.

As for a work around there is another method: It is possible to make another outbound call to a separate VoiceXML Application and connect it to the conference as another participant.

I hope this clears things up, please let us know if you have any further questions or concerns.

Regards,

Alex Bring
Voxeo Support
bpcamac
1/2/2009 8:15 PM (EST)
I am interested to know how that would work.  It had crossed my mind that if I could get the audio playing on another connection then I could just join it into the conference and then unjoin it when the dialog had finished.  But how to create a null connection?
bpcamac
1/2/2009 8:27 PM (EST)
On another subject: I really don't understand the difference between an argument that expects a variable name (e.g. dialogid above) and one that takes an ECMAscript expression (e.g. connectionid above).  But there is certainly a difference in behavior.  For instance:

<var name="myDialogID"/>
<var name="myConnectionID"/>
...

<!-- supply myDialogID as a variable and myConnectionID as ECMAscript refering to a variable -->
<dialogstart ... dialogid="myDialogID" connectionid="myConnectionID">

<!-- attempt to modify the variable -->
<log expr="'myDialogID=' + myDialogID"/> 
<assign name="myDialogID" expr="0"/>
<log expr="'myDialogID=' + myDialogID"/> 

<!-- attempt to modify the variable referenced by ECMAscript -->
<log expr="'myConnectionID=' + myConnectionID"/> 
<assign name="myConnectionID" expr="0"/>
<log expr="'myConnectionID=' + myConnectionID"/>
 
will produce:
log: myDialogID=(some string)
log: myDialogID=(!!surprisingly the same string!!)
log: myConnectionID=(some string)
log: myConnectionID=0 (!!as would be expected!!)

The strange part here is that attempts to modify the variable (myDialogID) have no effect. 

I don't get it.  MyDialogID is declared as a variable but after used by dialogstart for instance, its immutable!

MattHenry
1/2/2009 9:57 PM (EST)


Hi there Brenton,

I'm going to stick with an inline format to answer your questions, if that's cool with you:

"It is possible to make another outbound call to a separate VoiceXML Application and connect it to the conference as another participant."

Q: I am interested to know how that would work.  It had crossed my mind that if I could get the audio playing on another connection then I could just join it into the conference and then unjoin it when the dialog had finished.  But how to create a null connection?

A: Assuming that I am understanding the context correctly, this isn't really a "null" connection per-se. All we are doing is creating a new VXML application mapping, and assigning it an indial number that the CCXML can then call as a conference target. Works pretty well, but in a production capacity, does present some billing concerns to the end-user that are all too obvious, I'd think...



Q:  I really don't understand the difference between an argument that expects a variable name (e.g. dialogid above) and one that takes an ECMAscript expression (e.g. connectionid above).  But there is certainly a difference in behavior.

A: The dialogid is used as an anchor for events within the VXML context that we'd probably want to propagate to the CCXML session. Can't think of why we would want to modify it's value at runtime, and it might well be a read-only value: I haven't tested this particular facet of CCXML-VXML interaction, but the spec hints that it might be read-only:


http://www.w3.org/TR/ccxml/#dialogstart

"The value of the attribute must receive a dialog identifier value for the launched dialog interpreter instance."

The confusion here *might* stem from the difference between an ECMAScript expression, and an ECMAScript Left Hand Side Expression:

"ECMAScript left-hand-side expression - defined in ECMA-262 [ECMASCRIPT] 11.2; this is an expression which produces a result to which a value can be assigned; an expression which is valid as the left hand operand of an assignment (=) operator.."

"ECMAScript expression - defined in ECMA-262 [ECMASCRIPT] 11.1; this is an expression which produces a value; an expression which is valid on the right hand side of an assignment operator.."

See section 3.1 of the CCXML spec for examply-goodness.

=)

~Matt



bpcamac
1/3/2009 3:10 AM (EST)
Hi Matt,

Thanks for the quick response - as always.  Don't you guys ever sleep?

Continuing the inline Q&A format...

On the subject of Connections:  I hadn't thought about using a mapping.  I'll research it to see if it might be suitable for us.  Thanks for the tip.

On the subject of Variables and ECMAscript:  makes sense when you explain it that way - left-hand side expressions I understand.  I should have consulted the standard.  In my CCXML scripts I use the convention of setting that dialogID variable (now, a proxy variable) to zero when a dialog.exit is seen.  This way the script can determine if there is a vxml session attached to a ccxml connection or not, and take appropriate action. e.g. whether to terminate the dialog or move on.

cheers,
Brenton
voxeoAlexBring
1/3/2009 4:30 AM (EST)
Hello,
    Here at Voxeo we never sleep :)

Please let us know if you are in need of any assistance if you have any more issues, concerns, or questions regarding this topic, as we are always on stand by and ready to help.

Regards,

Alex Bring
Voxeo Support
ranm
7/15/2010 5:24 AM (EDT)
The note at the top of this page mentions: "The ability to play a dialog to a conference is only available in Prophecy 9."

Is it also possible to play a dialog to 2-party joins?
If yes, what would be the contents of the connection_id parameter?

Regards,
Ran
JustinDupree
7/15/2010 10:24 AM (EDT)
Hi,

While you can't play audio to a two party join, you can mostly certainly do it through a conference using Prophecy 9, which is available in our hosted environment for you to test. IF your goal is to simply play audio to two parties, then putting them in a conference could be a lot of 'trouble', so you may want to consider simply unjoining both callers (which happens instantly), play audio to them, and then rejoin them.

Hope that helps!  Let us know if we can be of further assistance.

Regards,

-Justin Dupree
jbgeraldino
3/13/2012 8:22 AM (EDT)
Hi,

Is there a way to get values from the variables inside the src URL?

Regards,
~JB
voxeoshanesmith
3/19/2012 4:05 PM (EDT)
Hi,

Do you mean once inside the VXML page? Our docs showing how to pass variables back and forth are located here:

http://docs.voxeo.com/ccxml/1.0-final/ccxml10_passtovxml.htm

If I've misunderstood, or something is working as you would expect, please let me know and I'd be glad to investigate furthers.

Regards,
Shane Smith
Voxeo Corporation

Status of Voxeo's Hosted Services: [link=http://status.voxeo.com/]status.voxeo.com/[/link]

Prophecy 11 Now Available: [link=http://docs.voxeo.com/prophecy/11.0/home.htm]docs[/link]  | [link=http://www.voxeo.com/prophecy/]download[/link]

login


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