CCXML Voxeo 1.0 Development Guide

| TOC

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.

Tutorial: Your First Dialog

This tutorial will explore the circuitous nature of CCXML/VoiceXML hybrid applications. Mixing call control and voice recognition is probably why you are here in the first place, so this may prove to be your first truly exciting tutorial; nevertheless, if you have not navigated the basic (and boring) concepts layed forth in tutorials one, two, three, and four, it is recommended you do so at this time. You have been warned.

In this tutorial, we will:

Learn about VoiceXML dialogs within a CCXML context
Learn how to pass variables between CCXML and VoiceXML dialogs

Step 1: creating our initial CCXML structure

From our previous tutorials, we now recognize the following structure as a normal starting point:


<?xml version="1.0" encoding="UTF-8"?>
<!-- NOTE THAT WE *MUST* DECLARE THE xmlns ATTRIBUTE --> 
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml"> 
</ccxml>

Step 2: setting up our basic handlers

We are already comfortable with state machines and handlers (both "event" and "error"), so let's take care of those first.


<?xml version="1.0" encoding="UTF-8"?>
<!-- NOTE THAT WE *MUST* DECLARE THE xmlns ATTRIBUTE --> 
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml"> 
  <var name="state0" expr="'init'"/>
  <eventhandler statevariable="state0">
    <transition state="'init'" event="connection.CONNECTION_ALERTING">
      <accept/>      
    </transition>

    <transition state="'init'" event="connection.CONNECTION_CONNECTED" name="evt">
      <log expr="'Houston, we have liftoff.'"/>
    </transition>

    <transition event="call.CALL_INVALID" name="evt">
      <exit/>
    </transition>

    <transition event="error.*" name="evt">
      <log expr="'Houston, we have a problem: (' + evt.error + ')'"/>
      <exit/>
    </transition>
  </eventhandler>    
</ccxml>

Step 3: the good stuff

Logging debug messages and handling badly named error messages may be exciting for fat guys programming in C++, but we are here to design phone markup scripts. We are fascinated by bright, shiny objects and the idea of speaking into a "smart phone" that can listen to our voices and actually understand. We marvel at this pinnacle of technology and want to take part; to join the band; to play an instrument; to fight SkyNet; to swim the English Channel; to eat uncooked pork. In CCXML, all of these are accomplished through "dialogs" that instantiate a VoiceXML session.


    <transition state="'init'" event="connection.CONNECTION_CONNECTED" name="evt">
      <log expr="'Houston, we have liftoff.'"/>

      <dialogstart src="'gimme.vxml'" dialogid="theDialog" 
                  type="'application/xml+vxml;platform=motorola'"/>

      <assign name="state0" expr="'dialogActive'" />
      
      <send event="'timeout'" target="session.id" delay="'20000'" /> 
    </transition>

Note: dialogs are not explicitly bound to calling only VoiceXML scripts, but for purposes of this tutorial, let's accept the hyperbole and move on. The <dialogstart> element is rather straightforward -- we hand it a source URL and a dialog name (the name is for CCXML event purposes only). That script is then executed by a VoiceXML server, running parallel to our CCXML session. Our beautiful, titanic, asynchronous state machine chugs along (la la la), waiting for a reply from the off-loaded dialog. Since we are crafty phone markup coders, we are also going to start a little timer, giving us a way to limit the amount of time callers may remain in the VoiceXML script. We set the maximum at 20 seconds... mark!

Meanwhile, let's check out "gimme.vxml":


<?xml version="1.0"?>
<vxml version="2.0">
  <form id="Form">
    <field name="input" type="digits">
      <prompt>
        Please say some numbers ...
      </prompt>
      <filled>				
        <exit namelist="input"/>
      </filled>
    </field>
  </form>
</vxml>

Yes, I know its a lame VoiceXML script... Look, it serves the didactic need, so stop complaining. Our simple voice reco <form> gathers some digits and then passes back to CCXML via the <exit> command. Notice the "namelist" attribute -- like all VoiceXML namelists, we can pass multiple variables back to our call control layer.

Step 4: doing something with the good stuff

Back in CCXML, we catch the "dialog.exit" event. You will notice below that our VoiceXML namelist variables have been transformed into "evt." variables. So what can we do with our new found input-gathering techniques? Really bright coders would have captured PIN information or maybe an outbound phone number to call. But we are not smart. We can't make things go. We will just spit out a <log> entry proving definitively, before God and Gene Roddenberry, that the variable was successfully based back into CCXML:


    <transition state="'dialogActive'" event="dialog.exit" name="evt">
      <log expr="'Houston, the dialog returned [' + evt.input + ']'" />
      <exit /> 
    </transition>

Finally, we need to have a catch <transition> for our timer, just in case someone from Florida calls and cannot remember elementary arithmetic in twenty seconds (Floridians are notoriously poor at making really simple decisions in a timely fashion). As with any asynchronous event queue, it is theoretically possible that the dialog and the "dialog.exit" event have already been placed in the queue after our "user.timeout" event has gone off. These "micro-timing" scenarios can and will crop up, further emphasizing the argument for properly designed state machines.


    <transition state="'dialogActive'" event="user.timeout">
      <log expr="'Houston, a timeout occured'" />
      <dialogterminate sessionid="theDialog" />
    </transition>

Now you can see why we gave our <dialog> a name designation -- this allows us to tear down the dialog for programmatic reasons later.

Step 5: let's wrap it up

Our seriously exciting script is now complete. The whole shebang looks like this:


<?xml version="1.0" encoding="UTF-8"?>
<!-- NOTE THAT WE *MUST* DECLARE THE xmlns ATTRIBUTE --> 
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml"> 
  <var name="state0" expr="'init'"/>
  <eventhandler statevariable="state0">
    <transition state="'init'" event="connection.CONNECTION_ALERTING">
      <accept/>      
    </transition>

    <transition state="'init'" event="connection.CONNECTION_CONNECTED" name="evt">
      <log expr="'Houston, we have liftoff.'"/>

      <dialogstart src="'gimme.vxml'" dialogid="theDialog" 
                  type="'application/xml+vxml;platform=motorola'"/>
      <assign name="state0" expr="'dialogActive'" />
      
      <send event="'timeout'" target="session.id" delay="'20000'" /> 
    </transition>

    <transition state="'dialogActive'" event="dialog.exit" name="evt">
      <log expr="'Houston, the dialog returned [' + evt.input + ']'" />
      <exit /> 
    </transition>

    <transition state="'dialogActive'" event="user.timeout">
      <log expr="'Houston, a timeout occured'" />
      <dialogterminate sessionid="theDialog" />
    </transition>
    
    
    <transition event="call.CALL_INVALID" name="evt">
            <voxeo:sendemail to="'yourEmail@there.com'" 
                        from="'myApp@here.com'" 
                        type="'debug'" 
                        body=" 'call.CALL_INVALID detected! ' "/>
      <exit/>
    </transition>

    <transition event="error.*" name="evt">
      <log expr="'Houston, we have a problem: (' + evt.error + ')'"/>
              <voxeo:sendemail to="'yourEmail@there.com'" 
                        from="'myApp@here.com'" 
                        type="'debug'" 
                        body=" 'generic error detected! ' "/>
      <exit/>
    </transition>
  </eventhandler>    
</ccxml>

Download the CCXML source code!

What we covered:

Learned how to call VoiceXML scripts from CCXML
Learned how to pass variables between CCXML and VoiceXML dialogs

ANNOTATIONS: EXISTING POSTS

awirtz

9/16/2005 2:28 PM (EDT)

Because of current limitations in Voxeo's CCXML/VXML integration, if the caller hangs up during a VXML dialog, the dialog.exit event cannot be generated.

This means that even if the VXML layer has a disconnect handler which executes an <exit> with a namelist, the data will never reach the CCXML layer.

(correct me if I'm wrong, but that is what I've seen in my testing)

mikethompson

9/16/2005 5:30 PM (EDT)

Hey Aaron,

You are indeed correct on this issue. When hanging up during a VXML dialog, the dialog.exit event is not going to be generated and thus the data never gets returned to the CCXML layer.

I spoke with engineering, and they are aware of this issue. The implementation of VoiceCenter 6 should fix this problem, which is expected to rollout later this year (Q4).

Cheers,
Mike Thompson
Voxeo Extreme Support

plcousins

6/5/2006 12:14 AM (EDT)

The documentation does not mention that data returned by the exit of a voicexml dialog in the namelist attribute is no longer in the root of the event object. It is in the values subobject. So in the example above, the log statement should not use 'evt.input', it should cite 'evt.values.input'.

mikethompson

6/5/2006 12:30 PM (EDT)

Hey Peter,

There appears to be some confusion going on here, allow me to elaborate. The CCXML tutorials in this documentation guide are actually part of Voxeo's own CCXML draft, from 2002.

We do actually have a CCXML 1.0 platform in our Prophecy platform which is based off of the June 2005 draft. However, we do not have a documentation set for this version as of yet. For now, the best help is going to be available via the w3c spec:

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

For Voxeo's 2002 build of CCXML, the exit namelist is stored in the evt object.

Hope this helps,
Mike Thompson
Voxeo Extreme Support

jeross1

2/9/2007 6:00 PM (EST)

Hi,
In the code snippet,

*****
<dialogstart src="'gimme.vxml'" name="theDialog"
type="'application/xml+vxml;platform=motorola'"/>
<assign name="state0" expr="'dialogActive'" />
*****

there is an attribute called "name". I'm not finding it in the specs. Have I overlooked something or should this attribute be "dialogid"?

Thanks,
-Judy

MattHenry

2/9/2007 9:06 PM (EST)

Hello Judy,

Correct you are! This tutorial was actually written *prior* to the CCXML spec of 2002, and this is an instance where we didn't properly update our code sample to match the spec. I'll see that this is fixed straightaway. Thanks for catching this for us!

~Matt

fayyazkl

3/14/2007 7:25 AM (EDT)

Hi,

I wanted to play a song and simultaneously record voice. For that matter i tried to execute two dialogs, one after the other witin one transition element. But they failed to execute! If comment any one of them, the other works fine.

I wanted to know if there is some restriction with this, since in conference i saw multiple call statements in a single transition element which is logically a similar process. Since dialog's execute asynchronously, so we should be allowed to execute them in parallel, please elaborate.

Thanks,

Fayyaz Khan Lodhi

VoxeoBrian

3/14/2007 10:59 AM (EDT)

Hello,

The best way to accomplish this is by making 2 separate calls to vxml applications, one to record the voice, the other to play the song, and then join them together in conference. You might like to read the documentation provided here: http://docs.voxeo.com/ccxml/1.0/t_6ccxml.htm . This should be helpful in accomplishing what you are looking for. If you need further clarification, we are always happy to help.

Regards

Brian

fayyazkl

3/19/2007 2:24 AM (EDT)

Hi Brian!

I use the account ticket to talk things to you but i got a differnt kind of response there. Further to your recommendation below regarding calling two separate vxml applications, i have done the same thing but it didnt work well.

What i did is that accept an inbound call, initiate a dialog which plays a .wav file, then call another application which records. Upon successful connection to application i join both call legs. However, code is behaving strangely. If i comment out the dialog of playing song, it works as expected. But if the dialog is there, the call is termnited just a second after its been picked up. I am using skype to make calls to my application, but for calling the seond application, i have a locally mapped DID. I am attaching the code. Please advise as i am feeling pretty awkward and i saw examples of whisper message doing the same i.e. initing a dialog then making call to an outbound number and then joining them. The difference ofcourse is, that i am calling another application instead of a normal phone.

Here is the code

<ccxml version="1.0">
<var name="state0" expr="'init'"/>
<eventhandler statevariable="state0">
<transition state="'init'" event="connection.CONNECTION_ALERTING">
<log expr="'ACCEPTING INBOUND CALL'"/>
<accept/>
</transition>

<transition state="'init'" event="connection.CONNECTION_CONNECTED" name="evt">
<var name="callid_in" expr="evt.callid"/>
<log expr="'INBOUND CALL CONNECTED'"/>
<assign name="state0" expr="'singing'"/>
<dialogstart src="'playsong.vxml'"/>
<createcall dest="'6174018634'"/>
</transition>
<transition state="'singing'" event="connection.CONNECTION_CONNECTED" name="evt">
<var name="callid_out" expr="evt.callid"/>
<log expr="'CONNECTED TO APPLICATION'"/>
<assign name="state0" expr="'recording'"/>
<join id1="callid_in" id2="callid_out"/>
</transition>

<transition state="'recording'" event="dialog.exit">
<log expr="'WE ARE DONE WITH RECORDING'"/>
<exit/>
</transition>
</eventhandler>
</ccxml>

MattHenry

3/19/2007 6:51 PM (EDT)

Hi there,

Please understand that it is going to take us some time to map your code locally and test this out to see where it is going wrong. In the future, I think it might be best to proceed with inquiries such as this by providing us with debugger output, which saves both of us a significant amount of time in providing a resolution to application-specific problems. Regardless, we will take a look at this, and do our best to see what we can do to help.

Regards,

~Matthew henry

voxeojeff

3/20/2007 5:54 PM (EDT)

Hello Fayyaz,

I see that you are interested in initiating a VXML dialog while simultaneously using CCXML's <createcall> to call into another application which records the user's voice, and the .wav file. Unfortunately, this is simply not possible with CCXML, and I apologize for any confusion you may have had. As stated in the other ticket you referred to, using pure VoiceXML and utilizing the <voxeo:recordcall> element would prove to be efficient. You may refer to this link for more information on <voxeo:recordcall>: http://docs.voxeo.com/voicexml/2.0/voxeo-recordcall.htm.

I hope this helps to clarify things for you.

Best,
Jeff Menkel
Voxeo Corporation

fayyazkl

3/21/2007 4:25 AM (EDT)

Hi Jeff,

Thanks for help and clarificaiton. I did a recording using voxeo:record call feature. However, the issue i am facing now is, when the applicaiton is called through a normal land line phone, and is recorded along with a song being played, the quality of vocals is very low and bearly audible. Instead when i recorded vocals using SKYPE, the quality of vocals was significantly higher and almost compareable to that of the song being played. Could you suggest any thing to resolve this issue? Since the target of our application would be users calling through ordinary phones.

Thanks,

Fayyaz Lodhi

voxeojeff

3/21/2007 4:45 PM (EDT)

Hi Fayyaz,

There are a lot of variables when it comes to sound quality, and many things in between the user and the VCS that records the call can play a part in why Skype sounds better to you than a normal phone. Sound quality and volume can be affected by changing simple things such as microphones, headsets, or phones. However, it also can be affected by the usage of different routes and different SBCs on our side. Simply using a different phone, or changing the volume on your Skype will affect the sound quality of your recording. I hope this helps shed some light on the matter.

Best,

Jeff Menkel
Voxeo Corporation

kave

9/1/2007 6:23 PM (EDT)

hi there!

this is about ... <dialogstart src="'gimme.vxml'"...

the file extension file always must be vxml ??? i mean, could i put on its extension "xml" too...???

like <dialogstart src="'gimme.xml'"...

where their content are the same ( gimme.xml = gimme.vxml)???? but the file extension are different

thanks in avance,

best
kave

mikethompson

9/2/2007 12:07 AM (EDT)

Hi Kave,

You can have the file extension as .xml if you like. The browser does not care about the file extension, so you could even use .txt or .php if it better suits you. Just make sure your invoked VXML document contains valid, well-formed XML, and all should be well. :)

Best,
Mike Thompson
Voxeo Corporation

Intro to Dialogs and CCXML

| TOC

| Call Legs: An Overview