CCXML Voxeo 1.0 Development GuideHome  |  Frameset Home
  CCXML Event Listing  |  TOC  |  E: ECMAScript and CCXML  
This documentation is for CCXML 1.0-Voxeo, which has been superceded by CCXML 1.0-W3C. The CCXML-Voxeo platform is not being updated any longer. The CCXML 1.0-W3C version, however, has many new features and is actively being enhanced. If you're writing a new CCXML application, you should use CCXML 1.0-W3C. Click here for the CCXML 1.0-W3C documentation.

Appendix D: Dialog Extensions

One of the biggest requirements for CCXML was to have the ability to direct a caller to a VoiceXML system. As you probably know already, such a transfer is called a dialog, with all the appropriate input and output capabilities that one would expect. As mentioned in the w3c specification, a dialog does not necessarily need to be on a VoiceXML platform only; the type attribute of the <dialogstart> element determines what backend it will actually be talking to.

The Voxeo CCXML platform takes advantage of this with four additional dialog types.


Dialog Type "audio/wav"

This is a very simple dialog type,  the src attribute determining the .wav file that should be played to the caller. Do note that the complete file will be played, and there is no way to abort the playback with the exception of the <dialogterminate> element being executed. As such, its intended purpose is for short audio prompts, or being used as 'hold music':


    <dialogstart src="'WaitingForYou.wav'"  type="'audio/wav'"/>


The Voxeo CCXML platform supports a variety of audio formats (see Appendix A for more details).  So technically speaking, you are not limited to .wav files only. You may also use HTTP, HTTPS, and FTP formatted URL's for this extension. When playback of the specified audio file has completed, a dialog.exit event will be sent back to the session.

In the event that there is a problem with playback, (a bad fetch due to a malformed URL, for instance), there will not be an error sent, although you can expect this behavior to change in the near future.


Dialog Type "application/x-fetchdigits"

Similar to the 'audio/wav' value, the 'application/fetchdigits' value is much more powerful. It allows for playback of an audio file, and the acceptance of DTMF input from the caller. If the specified audio file cannot be located, you also have the option of indicating a backup TTS string to be read to the caller. The formatting for this is indicated below:


    <dialogstart src="'http://MyServer.com/MyFile.wav?termdigits=*#&amp;text=Here is the TTS&amp;voice=English-Male3&amp;maxtime=10s'" type=" 'application/x-fetchdigits' "/>


Be aware that it is possible to simply indicate a TTS string to be played in lieu of a wav file, and even to change the TTS voice/gender:


    <dialogstart src="'null://?termdigits=123*#&amp;voice=English-Male2&amp;text=Listen to my groovy male voice'" type="'application/x-fetchdigits'"/>


Also, note that the only field that will be available in the dialogexit event is called digits, and contains the DTMF characters entered before the termdigit was pressed.

For example:


    <dialogstart src="'null://?termdigits=#&amp;text=press some digits, fool'"
                        type="'application/x-fetchdigits'"
                        name="D_1"/>
      .....

      <transition event="dialog.exit" name="evt">
        <if cond="'123' == evt.digits">
          ....
        </if>
      </transition>
          ....


As you can likely figure out on your own, the TTS outputs 'press some digits, fool', and after the caller enters DTMF input and hits the terminating digit,( 'dtmf-pound', in this case), the dialog then exits.  When we enter the dialog.exit transition if the sequence of digits pressed was '123', then we have fufilled a condition of the 'if' statement.


Dialog Type "application/x-senddtmf"

This dialog type simply plays DTMF tones to the caller.  Like the other dialog extensions, the pertinent information is passed in through the src attribute of the <dialogstart> element. There are also two additional parameters that we may use with this extension:



An example of this in action might look something like this:


<dialogstart src="'dtmf://1234?pause=200&amp;duration=100'"
                    type="'application/x-senddtmf'"
                    name="D_1">


Note that the DTMF formatting scheme is absolutely mandatory. The actual digits to output will be played in the order indicated in the URL path, (the above example would play out as 'dtmf-1, dtmf-2, dtmf-3, dtmf-4' to the caller). DTMF playback will only introduce problems if the URL is improperly formatted.


Dialog Type "application/x-recordaudio"

As an extra-special dialog type, the Voxeo CCXML implementation is capable of recording the incoming audio stream of a current, active call leg. Targets can be any .wav or .vox file on HTTP or FTP servers. A variety of URL parameters allow the fine-tuning of such a recording. The parameters supported are:


Also be aware that both relative and fiully qualified URLs are considered acceptable. For HTTP the upload method is "GET", which may require special configurations on some webservers. An example of this extension in action might look something like this:


    <dialogstart src="'ftp://ftp.foo.org/test.wav&amp;termdigits=1'"
                        type="'application/x-recordaudio'"
                        name="R_1"/>





  ANNOTATIONS: EXISTING POSTS
moshe
6/20/2004 4:32 PM (EDT)
Strings of the form

null://?termdigits=#&text=press some digits, fool'

don't work for me  -- it's a "&" in XML, which is results in a fatal parsing error. I use:

null://?termdigits=#&amp;text=press some digits, fool'

I.e., replace the "&" with the entity "&amp;
moshe
6/20/2004 4:34 PM (EDT)
Wow, let's try that again.

The &amp; character in the examples cannot be used directly, because the XML parser will complin about a &amp; character.

Instead, you must use &amp;amp;.

Now let's see if that goes through the HTML parser correctly!
moshe
12/28/2006 7:21 AM (EST)
Is it application/x-fetchdigits, as in the code sample, or application/fetchdigits, as in the text?
VoxeoBrian
12/28/2006 12:03 PM (EST)
Hello Moshe,

The former is correct.  Using 'application/x-fetchdigits', as shown in the sample code, should do the trick.

I hope this helps clarify.


Cheers

Brian
moshe
1/12/2007 6:49 AM (EST)
In the W3C compliant version of CCXML, the results are available in the event as values.termdigit and values.digits.

Also, please note that the final digit is not part of values.digits. That is, if termdigit is set to "#" and the person presses "123#", then values.digits will be "123" and values.termdigit will be "#."
jbassett
1/12/2007 8:59 AM (EST)
Hello,

Thanks for the information. We will review and make the appropriate changes.

Thanks
Jesse Bassett
Voxeo Support
voxeojeff
1/16/2007 6:38 PM (EST)
Hi Moshe,

I have whipped up a little sample code to illustrate your point regarding values.digits and values.termdigit in CCXML 1.0.
_______________________________________________________


<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml">

  <var name="state0" expr="'init'"/>

  <eventprocessor statevariable="state0">
 
  <transition state="init" event="connection.alerting" name="evt">
      <accept/>
  </transition>
   
  <transition state="init" event="connection.connected" name="evt">
    <dialogstart src="'null://?termdigits=#&amp;text=hey, press some digits, fool'"
                            type="'application/x-fetchdigits'"
                            dialogid="D_1"/>
  </transition>
 
  <transition state="init" event="dialog.exit" name="evt">
      <log expr="'values.digits = [' + evt.values.digits + ']'"/>
      <log expr="'values.termdigit = [' + evt.values.termdigit + ']'"/>
      <exit/>
  </transition>
 
  <transition event="error.*" name="evt">
    <log expr="'an error has occured: [' + evt.reason + ']'"/>
  </transition>

  </eventprocessor>
</ccxml>

_______________________________________________________


Thanks for the input, we appreciate it! ;-)


Best,

Jeff
moshe
1/24/2007 10:14 PM (EST)
I'd like some clarification on how x-recordaudio works. Does the stream flow in real time to the location designated by the src attribute, or does the platform record and then send? If the latter, what are the limitations (if any) on the length of the recording?
voxeojeff
1/25/2007 3:45 PM (EST)
Hi Moshe,

The 'x-recordaudio' dialog type does not allow for the stream of an active call leg to flow in real time to the src location.  The audio is recorded and then sent to it.  As for limitations, yes, there is a limit of 10 minutes for the 'maxtime' parameter.

Hope this helps.


Best,

Jeff Menkel
Voxeo Corporation
moshe
1/26/2007 10:44 AM (EST)
Jeff,

Thanks, that's useful to know. I've read that in VoiceXML, the limit is 120s, but that it can be extended in a production environment. Can CCXML's record also be extended to, say, an hour or more, in a production environment?

Moshe
voxeojeff
1/26/2007 2:13 PM (EST)
Hi Moshe,

According to our platform engineers, there appears to be no hard-coded limit for the maxtime parameter of x-recordaudio.  The 10 minute limit I spoke of applies to VoiceXML, although, it can be configured to record longer by adding a line like 'com.voxeo.voicecenter.maxtime.record=1000000' to the VoiceCenter-VoiceXML.properties file.  My apologies for the mistake.  :-)


Cheers,

Jeff Menkel
Voxeo Corporation
moshe
2/25/2007 6:33 PM (EST)
Does application/x-recordaudio also return other information, such as the duration of the recording? I don't see any such information in the event Object, but perhaps I'm overlooking something.
RobGreen
2/26/2007 1:45 PM (EST)
x-recordaudio returns back the following via the dialog.exit transition

[code]
event$.values.reason    - reason for dialog.exit event (noerror,termdigit,maxsilence,maxtime)
event$.values.termdigit  - if reason is 'termdigit' then the actual digit that was pressed
[/code]

record time is not specified.

rob
fayyazkl
3/14/2007 10:38 AM (EDT)

Hi,

Can i call a VXML application from within a CCXML application?
This is what tried:

          <createcall dest="'4073862174'"/>
          </transition>

          <transition state="'playing'" event="connection.CONNECTION_CONNECTED" name="evt">
<log expr="'CONNECTED TO APPLICATION. NOW ENTERING EXTENSION'"/>
                <dialogstart src="'dtmf://9990104955?pause=200&amp;amp;amp;duration=200'"
                  type="'application/x-senddtmf'"/>
          </transition>

Since, calling an application needs to enter the PIN after wards. I tried this but the application drops after a few minutes without playing the prompt of VXML application that i am calling. Please note that i am using SKYPE to call the first CCXML application. Could this be the possible reason?

Thanks for help.

regards,

Fayyaz
fayyazkl
3/14/2007 10:43 AM (EDT)

A Correction!

I mistaken pasted "&" repeatedely.

Correct code that i executed was:

                <dialogstart src="'dtmf://9990104955?pause=200&amp;duration=200'"
                  type="'application/x-senddtmf'"/>

Thanks,

Fayyaz
MattHenry
3/14/2007 1:18 PM (EDT)


Fayyaz,

I think that what you would want to do is to dial a direct-dial number instead of the 800+PIN service, which would preclude the need for a dialog extension to play "postdial" digit tones to the answering party, (our PIN system). Is there any reason why this would not work for you, based on the parameters of your application design?


~Matt
fayyazkl
3/15/2007 3:15 AM (EDT)

Thanks for response Matt!

Actually, i am sitting in Pakistan, and i am calling the first application through SKYPE, which in turn will call the second one. How do i map and dial a direct dial number. From the list of DD locations i saw at the bottom of application page, i understand that you mention  your (the caller's current location) to map a direct dial number. But in this case, the caller is another application hosted on your network . How do i manage to do that? Please explain!

Thanks,


Fayyaz
fayyazkl
3/15/2007 8:19 AM (EDT)

Dear Matt,

I tried mapping the DD number on my own and got it working. I realized that my assumption of local number is not an issue and i could call any directly mapped number from with in my applicatoin.

Thanks for support.

- Fayyaz
moshe
8/13/2007 6:10 AM (EDT)
For x-recordaudio: (a) what does the "name" attribute do? (b) How about a few short words regarding receiving the wav file that's been created? Presumably, I must expect a multipart MIME file similar to the one created by VoiceXML's record element.
moshe
8/13/2007 9:27 AM (EDT)
Please note that type "audio/wav" also accepts the ?text= format for tts. The text "null://?text=This is simple text" plays nicely.

login
  CCXML Event Listing  |  TOC  |  E: ECMAScript and CCXML  
© 2008 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site