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: Multi-party Conferencing in CCXML

This lesson will show you how to create a multi-party conferencing application utilizing CCXML. This tutorial assumes you have completed the previous lessons, and is not recommended as a starting point.

In this Lesson, we will:

Learn how to establish a multi-party CCXML conference
Learn how to <join> and <unjoin> call legs to the conference

Note: this tutorial requires the enabling of outdial priveleges on the Voxeo network, and the provisioning of a alphanumeric token string to your application. In order to get hooked up with all these neat features, check our Support Guide for all the juicy details.

Step 1: creating our initial CCXML structure

From our previous tutorials, we now recognize the following structure as a solid 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"> 

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

    <transition event="error.*" name="evt">
      <log expr="'---- an error has occurred (' + evt.error + ') ----'"/>
      <exit/>
    </transition>

  </eventhandler>    
</ccxml>

Step 2: Establishing the conference

Our conference is going to be triggered with an inbound call. Once we accept the "master" call, we will place three outbound phone calls and attach them all to the conference. This is not the classic "party line" style conference, but we are just getting started here. Small steps Sparks, small steps...


    <transition state="'init'" event="connection.CONNECTION_ALERTING" name="evt">
      <log expr="'---- assigning incoming callid to [line_0] ----'"/> 
      <var name="line_0" expr="evt.callid"/> 
      <log expr="'---- creating conference ----'"/>
      <createconference id="smallConf" /> 
    </transition>
    
    <transition state="'init'" event="ccxml.conference.created">
      <assign name="state0" expr="'docalls'"/> 
      <log expr="'---- conference created and its ID is [' + smallConf + '] ----'"/> 
      <log expr="'---- accepting incoming call [line_0] ----'"/>
      <accept callid="line_0"/>  
      <log expr="'---- making outbound calls ----'"/>
      <createcall dest="'4078351111'" name="line_1" /> 
      <createcall dest="'4078351112'" name="line_2" /> 
      <createcall dest="'4078351113'" name="line_3" /> 
    </transition>

Our two <transition> elements handle everything we discussed above. We have created a conference with the <createconference> element. When the "ccxml.conference.created" event is captured we <accept>ed the inbound call, and placed our three outbound calls. Our <createconference> tag requires one attribute (id), which represents the variable holding our conference ID. This will be used programmatically later in our application. Also, we are not accepting our inbound call nor placing any outbound calls until the conference itself has been successfully established -- this will prevent race conditions where our calls are answered but there is no conference for them to <join>. For sake of simplicity, we will call my second cousins in Apopka, FL (they don't work much, so they got plenty of time to answer the phone).

Step 3: Putting people in contact with people

The structure surrounding multi-party conferencing is not difficult. Once our nifty conference has been created, we may use the <join> and <unjoin> tags to insert and remove calls. The details simply depend on the conditions we want to use for <join>ing and <unjoin>ing. For now, let's keep it as simple as possible: when Buford, Del Ray, and Betty Sue answer, we will conference them in. When they hang up, or accidentally drop the phone in the canal, we will un-conference them.


    <transition event="connection.CONNECTION_CONNECTED" name="evt">
      <log expr="'---- call leg ' + evt.callid + ' has been answered ----'"/>
      <join sessionid1="evt.callid" sessionid2="smallConf"/> 
    </transition>

    <transition event="ccxml.conference.joined" name="evt">
      <log expr="'---- call leg ' + evt.callid + ' has joined the conference ----'"/> 
    </transition>
    
    <transition event="ccxml.conference.unjoined" name="evt">
      <log expr="'---- call leg ' + evt.callid + ' has unjoined the conference ----'"/> 
    </transition>     

    <transition event="call.CALL_INVALID" name="evt">
      <if cond="evt.callid == line_0">         
        <destroyconference id="smallConf"/>
        <assign name="state0" expr="'conferencedestroyed'"/> 
      </if>
    </transition>

Our first <transition> shows how simple the conferencing process is. We receive a "connection.CONNECTION_CONNECTED" event and use the <join> tag to tie two "calls" together. Of course, instead of two normal calls, we are using the callid for the recently answered outbound call and the conference's ID (housed in our variable named "smallConf").

Our successful <join> will toss the "ccxml.conference.joined" event. Here we simply spit out a log message, but nothing further. I snuck a bit of logic into our last <transition> -- when CCXML receives a "call.CALL_INVALID" event (for normal people, this means a "hangup" event), the call leg will automatically be removed from the conference without the need to use the <unjoin> tag (as you may have surmised, both the "call.CALL_INVALID" and "ccxml.conference.unjoined" events will be thrown by CCXML when a call leg in a conference ends the call).

So for our little application, we do not worry about the "hangup" event except if the original inbound call (termed the "master" call earlier) is the call leg in question; however, when the "master" call hangs up, we want to end the conference entirely. This is done with <destroyconference>, a bold and aggressive sounding CCXML tag.

Step 4: Clean up

For cleanliness, we have two more events needing to be handled:


    <transition event="ccxml.conference.destroyed">
      <exit/> 
    </transition>

    <transition state="'docalls'" event="error.*" name="evt">
      <log expr="'---- the problem was ' + evt.error + ' ----'"/> 
      <log expr="'---- killing the conference as a result ----'"/> 
      <destroyconference id="smallConf"/>
      <exit /> 
    </transition>

The first is very straightforward. Our conferencing application has no purpose in life once the conference has been destroyed, so we want to catch our "ccxml.conference.destroyed" event and <exit>. Our last event handler is needed for an error situation cropping up before the conference was properly torn down. This helps to avoid "zombie" conferences on CCXML server.

Step 5: The complete script

Here it is Sparks. Be sure to speak loudly for Del Ray -- he can't hear too well after the pit bull attack.


<?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" name="evt">
      <log expr="'---- assigning incoming callid to [line_0] ----'"/>
      <var name="line_0" expr="evt.callid"/> 
      <log expr="'---- creating conference ----'"/>
      <createconference id="smallConf"/> 
    </transition>
    
    <transition state="'init'" event="ccxml.conference.created">
      <assign name="state0" expr="'docalls'"/>
      <log expr="'---- conference created and its ID is [' + smallConf + '] ----'"/>
      <log expr="'---- accepting incoming call [line_0] ----'"/>
      <accept callid="line_0"/>  
      <log expr="'---- making outbound calls ----'"/>
      <createcall dest="'4078351111'" name="line_1"/> 
      <createcall dest="'4078351112'" name="line_2"/> 
      <createcall dest="'4078351113'" name="line_3"/> 
    </transition>
  
    <transition event="connection.CONNECTION_CONNECTED" name="evt">
      <log expr="'---- call leg ' + evt.callid + ' has been answered ----'"/>   
      <join sessionid1="evt.callid" sessionid2="smallConf"/> 
    </transition>

    <transition event="ccxml.conference.joined" name="evt">
      <log expr="'---- call leg ' + evt.callid + ' has joined the conference ----'"/> 
    </transition>
    
    <transition event="ccxml.conference.unjoined" name="evt">
      <log expr="'---- call leg ' + evt.callid + ' has unjoined the conference ----'"/> 
    </transition>     

    <transition event="call.CALL_INVALID" name="evt">
      <if cond="evt.callid == line_0">         
        <destroyconference id="smallConf"/>
        <assign name="state0" expr="'conferencedestroyed'"/> 
      </if>
    </transition>    
    
    <transition event="ccxml.conference.destroyed">
      <exit/> 
    </transition>

    <transition state="'docalls'" event="error.*" name="evt">
      <log expr="'---- the problem was ' + evt.error + ' ----'"/> 
      <log expr="'---- killing the conference as a result ----'"/> 
       <voxeo:sendemail to="'yourEmail@there.com'" 
                        from="'myApp@here.com'" 
                        type="'debug'" 
                        body=" 'conference error detected ! ' "/>
      <destroyconference id="smallConf"/>
      <exit/> 
    </transition>

    <transition event="error.*" name="evt">
      <log expr="'---- an error has occurred (' + 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:

Creating multi-party conferencing with CCXML
The proper method of cleaning up inactive conference legs
Benefits of avoiding Apopka, FL.

ANNOTATIONS: EXISTING POSTS

rtestard

11/15/2006 2:22 PM (EST)

Hi,

I am trying this code on my laptop with prophecy installed on it but it won't work.....I must have done something wrong for the outbound calls....but what !!!

My SIP provider for outbound calls is internetcalls and I have replaced the createcall tag with

<createcall dest="'0044XXXXXXXXXX@connectionserver.internetcalls.com'" name="line_1"/>

I have also set-up the VoIP settings with my internetcalls account (ID, password, VCS, nothing in NAT settings even if I have a private IP address).

Can anyone please tell me what I did wrong??? (do I need NAT settings, did I write the createcall wrong or is-it just impossible to initiate outbound calls with the downloadable Prophecy ???

Thanks a lot!!

mikethompson

11/15/2006 4:51 PM (EST)

Hi Romain,

We would love to help you troubleshoot your VOIP problems, but our documentation post section is not the best place to do so. If you would like, please open a private account ticket or open a thread in one of our public forums and we would be glad to help you out.

Best,
Mike Thompson
Voxeo Corporation

haigang

11/22/2006 2:21 AM (EST)

I have a question:only a inbound call trigger a conference?

jbassett

11/22/2006 4:57 AM (EST)

Hello,

Outbound will work as well. This tutorial is an example of an outbound call initiating a multi-party conference.

Thanks
Jesse Bassett
Voxeo Support

kave

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

hi there,

Sorry about asking a lot but, i want to take advantage on multy-party conferecing, so i was wondering if i could create a multy-party conference with the SIP PHONE ( i realised it has three lines) , but ? is that psosible? i mean, i want to create three asynchronus inbound calls, then these calls would connect between them for creating a dual-duplex communication (a conference), obviosly a "master" call would create the conference, but how could i join the second one and the third one call to this conference if they are inbound calls? in this example shows the other 3 ones are outbounds calls.... if i'll break my mind doing this, it will be possible to do it?

best

kave

mikethompson

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

Kave,

You can certainly create a multi-party conference with strictly inbound callers. While our documentation does not have an explicit example of this, our in-house CCXML gurus might have some sample code illustrating this. If you would be so kind, stay tuned and I will have some information for you once I have a chance to speak with them.

Best,
Mike Thompson
Voxeo Corporation

mikethompson

9/17/2007 3:38 PM (EDT)

Hi Kave,

I believe you already have this sample script, but I wanted to put this out there for all our other developers. Below is an conferencing application which is strictly for inbound callers only. It prompts the user for a conference ID, then joins them into the conference they chose. Bear in mind, this application is for CCXML W3C 1.0, which is a bit different from CCXML Voxeo. We actually just opened our W3C 1.0 documentation to the public, which can be found here:

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

Enjoy!

Mike Thompson
Voxeo Corporation

<?xml version="1.0" encoding="UTF-8" ?>

<ccxml version="1.0">


<var name="call_0"/>
<var name="myConfID"/>


<var name="getConfID_Dlg"/>
<var name="joinTheConf_Dlg"/>
<var name="leftTheConf_Dlg"/>
<var name="noInput_Dlg"/>


<var name="nextEvent"/>
<var name="audioPath" expr="'../audio/'"/>
<var name="state_0" expr="'init'"/>

<eventprocessor statevariable="state_0">





<transition state="init" event="connection.alerting" name="event$">
<assign name="call_0" expr="event$.connectionid"/>
<accept connectionid="call_0"/>
</transition>

<transition state="init" event="connection.connected" name="event$">
<log expr="'*** CALL CONNECTED ***'"/>
<assign name="state_0" expr="'connected'"/>
<send name="'getConfID'" target="session.id" targettype="'ccxml'"/>
</transition>

<transition event="connection.disconnected" name="event$">
<log expr="'*** CALL DISCONNECTED ***'"/>
<exit/>
</transition>





<transition event="getConfID" name="event$">
<assign name="state_0" expr="'getConfID'"/>
<dialogstart src="audioPath + 'enterConferenceID.wav?termdigits=#&maxtime=10000&text=Enter your conference I D followed by the pound key.'"
type="'application/x-fetchdigits'"
dialogid="getConfID_Dlg"
connectionid="call_0"/>
</transition>

<transition event="joinTheConf" name="event$">
<assign name="state_0" expr="'joinTheConf'"/>
<dialogstart src="audioPath + 'joinTheConference.wav?text=You will now join the conference. Press the pound key to exit without disconnecting.'"
type="'audio/wav'"
dialogid="joinTheConf_Dlg"
connectionid="call_0"/>
</transition>

<transition event="leftTheConf" name="event$">
<assign name="state_0" expr="'leftTheConf'"/>
<dialogstart src="audioPath + 'leftTheConference.wav?termdigits=123&maxtime=30000&text=You have left the conference. Press one to disconnect. Press two to rejoin, or press three to join a different conference.'"
type="'application/x-fetchdigits'"
dialogid="leftTheConf_Dlg"
connectionid="call_0"/>
</transition>

<transition event="playNoInput" name="event$">
<assign name="state_0" expr="'playNoInput'"/>
<dialogstart src="audioPath + 'noInput.wav?text=I am sorry. I did not hear anything.'"
type="'audio/wav'"
dialogid="noInput_Dlg"
connectionid="call_0"/>
</transition>





<transition state="getConfID" event="dialog.exit" name="event$">
<if cond="event$.values.digits == ''">
<log expr="'*** USER DID NOT ENTER CONFERENCE ID ***'"/>
<assign name="nextEvent" expr="'getConfID'"/>
<send name="'playNoInput'" target="session.id" targettype="'ccxml'"/>
<else/>
<log expr="'*** CONFERENCE ID ENTERED: [' + event$.values.digits + '] ***'"/>
<createconference conferenceid="myConfID" confname="event$.values.digits"/>
</if>
</transition>

<transition state="joinTheConf" event="dialog.exit" name="event$">
<log expr="'*** JOINING CONFERENCE ***'"/>
<join id1="call_0" id2="myConfID" entertone="'true'" exittone="'true'" voxeo-termdigits="'#'"/>
</transition>

<transition state="leftTheConf" event="dialog.exit" name="event$">
<log expr="'*** USER PRESSED: [' + event$.values.termdigit + '] ***'"/>
<if cond="event$.values.termdigit == 1">
<log expr="'*** USER CHOSE TO DISCONNECT ***'"/>
<disconnect connectionid="call_0"/>
<elseif cond="event$.values.termdigit == 2"/>
<log expr="'*** USER CHOSE TO REJOIN CONFERENCE ***'"/>
<send name="'joinTheConf'" target="session.id" targettype="'ccxml'"/>
<elseif cond="event$.values.termdigit == 3"/>
<log expr="'*** USER CHOSE TO JOIN NEW CONFERENCE ***'"/>
<send name="'getConfID'" target="session.id" targettype="'ccxml'"/>
<else/>
<log expr="'*** USER DID NOT PRESS A TERMDIGIT ***'"/>
<assign name="nextEvent" expr="'leftTheConf'"/>
<send name="'playNoInput'" target="session.id" targettype="'ccxml'"/>
</if>
</transition>

<transition state="playNoInput" event="dialog.exit" name="event$">
<log expr="'*** NOIMPUT DIALOG COMPLETE / THROWING NEXT EVENT: [' + nextEvent + '] ***'"/>
<send name="nextEvent" target="session.id" targettype="'ccxml'"/>
</transition>





<transition event="conference.created" name="event$">
<log expr="'*** CONFERENCE CREATED ***'"/>
<send name="'joinTheConf'" target="session.id" targettype="'ccxml'"/>
</transition>

<transition event="conference.joined" name="event$">
<log expr="'*** CALL JOINED TO CONFERENCE ***'"/>
</transition>

<transition event="conference.unjoined" name="event$">
<log expr="'*** CALL UNJOINED FROM CONFERENCE ***'"/>
<send name="'leftTheConf'" target="session.id" targettype="'ccxml'"/>
</transition>





<transition event="error.*" name="event$">
<log expr="'*** AN ERROR HAS OCCURRED: [' + event$.error + '] ***'"/>
<exit/>
</transition>
</eventprocessor>

</ccxml>

kave

9/18/2007 3:14 AM (EDT)

HI there!!

hey Mike thanks a lot!!!!

well, i was only trying to create a conference but i couldn't achieve it, the below code is taken from yours, like an example, this code only say to every user that he/she is going to be joined to the conference, by the VXML Dialog he gets informed about it (no password and authentication are tried it here) just a welcome Dialog, i tried it but it dind't work, i'm still trying it but i would like to know if you can give me a hand with this... ohh i almost forget it! i have realised that when i try to call to the application (index.xml CCXML file) skype always shows me that it's busy...

thanks a lot and i'll keep in touch

Best,
Kave

pd: obviously, i specified on "apliccation manager" that it is a application type of "Prophecy 7.0 - CCXML W3C 1.0"

index.xml

<?xml version="1.0" encoding="UTF-8" ?>

<ccxml version="1.0">


<var name="call_0"/>
<var name="myConfID"/>
<var name = "valuew" exp="1"/>
<var name="state_0" expr="'init'"/>

<eventprocessor statevariable="state_0">





<transition state="init" event="connection.alerting" name="bevent">
<assign name="call_0" expr="bevent.connectionid"/>
<accept connectionid="call_0"/>
</transition>

<transition state="init" event="connection.connected" name="bevent">
<log expr="'*** CALL CONNECTED ***'"/>
<assign name="state_0" expr="'connected'"/>
<send name="'getcardau'" target="session.id" targettype="'ccxml'"/>
</transition>

<transition event="connection.disconnected" name="bevent">
<log expr="'*** CALL DISCONNECTED ***'"/>
<exit/>
</transition>





<transition event="getcardau" name="bevent">
<assign name="state_0" expr="'getConfID'"/>
<dialogstart src="'gimme.xml'"
type="'application/xml+vxml'"
connectionid="call_0"/>
<assign name="state0" expr="'dialog_1'" />
</transition>




<transition state="dialog_1" event="dialog.exit" name="bevent">
<createconference conferenceid="myConfID" confname="valuew"/>
</transition>

<transition state="joinTheConf" event="dialog.exit" name="bevent">
<log expr="'*** JOINING CONFERENCE ***'"/>
<join id1="call_0" id2="myConfID" entertone="'true'" exittone="'true'"/>
</transition>





<transition event="conference.created" name="bevent">
<log expr="'*** CONFERENCE CREATED ***'"/>
<send name="'joinTheConf'" target="session.id" targettype="'ccxml'"/>
</transition>

<transition event="conference.joined" name="bevent">
<log expr="'*** CALL JOINED TO CONFERENCE ***'"/>
</transition>

<transition event="conference.unjoined" name="bevent">
<log expr="'*** CALL UNJOINED FROM CONFERENCE ***'"/>
<exit/>
</transition>





<transition event="error.*" name="bevent">
<log expr="'*** AN ERROR HAS OCCURRED: [' + bevent.error + '] ***'"/>
<exit/>
</transition>
</eventprocessor>
</ccxml>

gimme.xml (welcome code)

<?xml version="1.0"?>
<vxml version="2.0">
<form>
<block>
hi!! you are going to be joined!!! enjoy it!!
</block>
</exit>
</form>
</vxml>

mikethompson

9/18/2007 10:45 AM (EDT)

Hi Kave,

What exactly is happening with this script? The output from the real-time debugger logs would be most useful to troubleshoot your application. Would you be so kind as to call into the application with the real-time debugger open, and submit the results to support via the support tab at the top of the debugger page?

Also, I should mention you do not need to spawn vxml scripts to simply say "you will now join the conference." Simple TTS messages like that can be handled at the CCXML scope now, via dialog extensions. In fact, we are already using that same string of text in the sample script below:

<transition event="joinTheConf" name="event$">
<assign name="state_0" expr="'joinTheConf'"/>
<dialogstart src="audioPath + 'joinTheConference.wav?text=You will now join the conference. Press the pound key to exit without disconnecting.'"
type="'audio/wav'"
dialogid="joinTheConf_Dlg"
connectionid="call_0"/>
</transition>

Best,
Mike Thompson
Voxeo Corporation

kave

9/18/2007 1:39 PM (EDT)

Hi mike!

i was having a typo error with the attribute "exp" on the var tag ( "valuew"), i changed (exp="1") to (exp="'a1'"), but when i tested the application again and i took a look on "Application Debugger", this is what i get...

00003 3617 4:58:28 PM loading first document "http://webhosting.voxeo.net/25828/www/index.xml
00004 3617 4:58:28 PM error: compilation failed (error (1, 9) "The XML or Text declaration must start at line/column 1/1")
00006 3617 4:58:28 PM session exit reached

i can't exactly get what it means, but i'm trying to

Thanks a lot!

Regards
Kave

mikethompson

9/18/2007 2:12 PM (EDT)

Hi Kave,

If you try to pull up the start URL, you will notice there is an invalid character at the start of your document:

�<?xml version="1.0" encoding="UTF-8" ?>

Specifically, the � needs to be removed. Once that's removed, give your application another try, as it should resolve the issue for you.

Best,
Mike Thompson
Voxeo Corporation

kave

9/19/2007 12:10 AM (EDT)

Hi Mike!!!

The application Debugger has been very useful to me!!!, i removed this weird error and also in the begining i had newbie mistakes and troubles , but i checked out the log call bugs with the debbuger and i fixed it and then i could create the conference!!! :) it's so cool!!!, obviouly i know that for simple prompts like this one, i should use TTS on CCXML files, but in this case i was trying to test the VXML files for my tough application.

thanks a lot pal!!! this application is really interesting 'cause i have learned a lot about it!

have a nice day!!!

best,
kave

kave

9/19/2007 1:30 AM (EDT)

Hi Mike...

i forgot to ask you about something, can i play VXML that prompt Spanish dialogs when i use CCXML dialogstart? because the below script i tried it but it didn't work :( but when i tried to verify if this script was written fine with the platform Multi-Language - VoiceXML, it worked fine , but does CCXML have a multi-language platform as Prophecy 7.0 - Multi-Language - VoiceXML ??? how could i work with CCXML and VXML Spanish dialogs? is that possible?

thank again!!! a lot!!!

Best,
kave

pd: when i ran the application with a VXML spanish dialog, it didn't prompt anything, just join the user into the conference.

<?xml version="1.0"?>
<vxml version="2.0" xml:lang="es-ES">
<form>
<block>
Seras ingresado a la conferencia, bienvenido
</block>
</form>
</vxml>

kave

9/19/2007 2:01 AM (EDT)

Hi Mike!

Well, Jesse has allowed me to access to Prophecy 7.0 - Multi-Language - CCXML 1.0 , and all this work perfectly :)...

thanks a lot i'll keep in contact , i just want to say thanks for all again!!!!

Have a nice day!!!!

Best,
Kave

Multi-Party Conferencing

| TOC

| A: Audio Files & CCXML