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.

Duplex and Half Duplex Conferencing

So we have covered CCXML conferencing in our Lessons, and have messed with some of the neater tricks of the trade with HTTP-initiated outbound calls. Let's now tackle how to create an 'eavesdropping' conference call, where we have a single 'moderator' who will monitor the course of the conversation. Of course, while we want the moderator to be able to hear the participants speaking, we want to mask any sound coming from this heavy-breathing moderator, so our conference participants can have an uninterrupted chat. To do so, we will access the 'duplex' attribute of the <join> element.

Note: This example application 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.

So what exactly does the term 'duplex' mean to us in the context of the CCXML application? A look at any telephony dictionary indicates how this factors into this little experiment:

Full duplex is data transmission that takes place in two directions simultaneously, which is essentially any telephone call. Since data transmission happens at the same time in both directions, both caller and callee can interrupt the other, talk over each other, etc.

Half duplex allows data transmission in but one direction. A half-duplex connection is much like talking with any teenager, you can talk until you are blue in the face, but they won't hear a word you say.

With us so far? Let's now take a peek at how we can use duplex and half-duplex connections to string us together an eavesdropping application. For this sample application, we will assume that the moderator/admin will be based on the caller's ANI value. We will also allow for a three-digit conference ID for all participants, so our conference mixer isn't limited to but one conference at a time. So, let's start out simple, and first take a peek at the VXML dialog that will be invoked when we get a caller dialing into the app:

The VoiceXML Dialog


<?PHP
echo "<?xml version=\"1.0\"?>";
?>

<vxml version="2.1">
<meta name="maintainer" content="yourEmail@here.com"/>

   <log expr="'*** session.callerid =' + session.callerid"/>
   <var name="admin" expr="'no'"/>
   <var name="callid" expr="'<?php echo $HTTP_GET_VARS["session_callerid"]; ?>'"/>     

  <form>

    <field name="verify" type="digits?length=3">
      <prompt>
       <break/>
        Enter your conference ID now.
      </prompt>
      <filled>
          <if cond="callid == '<!--*** SOME CALLER ID *** -->'">
            <assign name="admin" expr="'yes'"/>
          </if>
          <exit namelist="verify admin"/> 
      </filled>
    </field>

  </form>
</vxml>

Nothing to it, right? As promised, we base Admin status on CallerID, and have a simple form/field/filled to take the conference ID from the caller, at which point we will return to our CCXML application.

The CCXML wrapper

What's so different about this CCXML code from what we have seen thusfar? Not all that much, truth be told. We are going to want to keep track of all conference participants, but this is good practice, anyhow. Letting folks join 'willy nilly' and not having proper cleanup code can lead to 'zombie' sessions, which is bad all the way around. So, once we have the logic in place to track when a caller enters the conferencing fray, we also want to catch when someone leaves the party, and track that as well. Once we programatically determine that there is no one left on the conference, we destroy the conference, thus making everyone happy. Including the Voxeo Engineers.

The other Big Difference between the below code and what we are already familiar with, is that of the conference Moderator. Remember, we assigned the Admin status via ANI in the VXML dialog, and passed this status variable to the CCXML by way of the <exit namelist> element/attribute. So, when the CCXML layer figures out that there is an Admin coming in, it will create a half duplex connection, and sit in a holding pattern until we have more people to join the conference. When we have a 'ham and egger', (non-admin), join the conference, then the CCXML layer will programatically create a full duplex connection, allowing all the non-admins to chat.


<?PHP
echo "<?xml version=\"1.0\"?>"
<ccxml version="1.0">
  <var name="state0" expr="'init'"/>

  <!--
  Initially, the admin variable is 'no'. You can reset it to 'yes' based on 
  any criteria you like (database info, callerID, etc.. In this example, we use
  callerID
  -->
  <var name="admin" expr="'no'"/>
  
  <!-- 
  Tracking number of particpants so we do not leave zombie conferences 
  this variable should reference a session variable or database query
  on the developer side.
  -->
   <var name="participants" expr="0"/>
  
  <!--
  Track joinstatus of each caller so we do not decrement participants on unjoin 
  and hang up
  -->	
  <var name="joinstatus"/>
  
  <eventhandler statevariable="state0">

  <!-- incoming call -->  
    <transition state="'init'" event="connection.CONNECTION_ALERTING" name="evt">
      <var name="line_0" expr="evt.callid" /> 
      <accept/> 
    </transition>

  <!-- incoming call connected -->
    <transition state="'init'" event="connection.CONNECTION_CONNECTED">
      <log expr="'---- Master call answered...'"/>
  <!-- newly connected call must log in -->
      <log expr="'---- starting the login vxml ...'"/>     
      <assign name="state0" expr="'login'" /> 			  
      <dialogstart src="'ccxml_vxml.php'" name="loginscr" type="'application/xml+vxml;platform=motorola'"/>
    </transition>	

  <!--
  Caller enters an arbitrary code (which is the conferenceID.
  If another caller enters the same code, they'll join that same conference.
  We advise protecting conferences with more authentication; 
  this is just an example.
  -->
    <transition state="'login'" event="dialog.exit" name="evt">
      <log expr="'---- Ended vxml login...'"/>
      <log expr="'---- About to create conference...'"/>
      <assign name="state0" expr="'conference'" /> 					
  <!--
  In the vxml dialog, based on the ANI, we assign a variable 'admin'.
  Below, if the admin = 'yes' we assign a CCXML variable admin = 'yes'
  -->
      <if cond="evt.admin == 'yes'">         
        <assign name="admin" expr="'yes'" />
      <else/>
        <assign name="admin" expr="'no'" /> 					
      </if>
      <createconference name="smallConf" voxeo-confname="evt.verify"/>
    </transition>	
    
	
    <transition state="'conference'" event="ccxml.conference.created">
      <log expr="'---- conference created and its ID is [' + smallConf + ']'" /> 
  <!--
  Here if our CCXML variable admin == 'yes' then that caller joins the 
  conference in listen-only mode 
  -->	
      <if cond="admin == 'yes'">         
        <join sessionid1="line_0" sessionid2="smallConf" duplex="'half'"/> 
      <else/>
         <join sessionid1="line_0" sessionid2="smallConf" duplex="'full'"/> 
      </if>
    </transition> 

    <transition event="ccxml.conference.joined" name="evt">
  <!--
  Here we'll increment the number of conference participants
  again... participants references a session variable or something
  visible to all clients
  -->
      <assign name="participants" expr="participants+1" /> 
      <assign name="joinstatus" expr="'joined'" /> 	  					
      <log expr="'---- call leg ' + evt.callid + ' has joined the conference'" /> 
    </transition>
    
    <transition event="ccxml.conference.unjoined" name="evt">
  <!--
  Here we'll decrement the number of conference participants
  again... participants references a session variable or something
  visible to all clients
  -->
      <assign name="participants" expr="participants-1" /> 
      <assign name="joinstatus" expr="'unjoined'" /> 	 
      <log expr="'---- call leg ' + evt.callid + ' has unjoined the conference'" /> 
    </transition>     

    <transition event="call.CALL_INVALID" name="evt">
      <if cond="joinstatus == 'joined'">         
        <assign name="participants" expr="participants-1" /> 					
      </if>
  <!--
  When you are tracking # of participants with a session variable, you will
  want to re-include this so you do not leave zombie conferences.
  -->
       <if cond="participants == 0">         	  		
         <destroyconference conferenceid="smallConf" />
         <assign name="state0" expr="'conferencedestroyed'" />
       <else/>
         <exit/>           
       </if>
    </transition>    
    
    <transition event="ccxml.conference.destroyed">
      <exit/> 
    </transition>


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

  </eventhandler>    
</ccxml>

Sample Code, Anyone?

You wanted it, you got it right HERE!

ANNOTATIONS: EXISTING POSTS

kave

9/5/2007 1:20 AM (EDT)

hi there!

i just was looking for information about a half-duplex conference and it seems that i found it :), i want that three users just get connected, and when if they were in, an only automatic dialogstart would talk to them and they only would listen the automatic dialog, , but would this code help me to create this type of conference where three inbound calls get connected where anybody of them is an admin user? just three happy guys or girls trying to listen a dialog from a conference. :), or i always must create an admin user?

thanks in avance

kave

mikethompson

9/5/2007 11:21 AM (EDT)

Kave,

While I don't have a CCXML document illustrating everything you're after, I certainly have a template you can use. This document is a bare bones, full-duplex CCXML conference that is all inbound (no outbound calls are spawned here and no single admin). All that is really left to add is a call out to a VXML application which is then joined into the conference for your users to listen to.

I should mention, this example is for the newest version of our CCXML platform (Prophecy - CCXML 1.0). We will be releasing our documentation set for this platform shortly, but I wanted to get you this code ahead of time, as CCXML 1.0 is more powerful than CCXML Voxeo (based on the October 2002 w3c draft). You should be able to create a CCXML 1.0 application within your Voxeo Application Manager. Do let me know if you have trouble accessing this platform and I will make sure you get access.

Again, I would save this template locally, as it's a great place to start all your conferencing applications. :)

Best,
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/6/2007 12:39 PM (EDT)

Hi Mike!!!

Thanks a lot again, i will try it out and later i will inform you about it, these days i was so busy and until now i will start to analyse this code, i'll let you know if i have any doubt about it.

Also i was working with Prophecy 7.0.... but now, i'm going to download the lastest version, i will let you know if i have some problems working with Voxeo Application Manager, i have been learning about CCXML from this tutorial, so i think i should go deeper into CCXML 1.0 like you say, it's very interisting how voxeo pals have created voxeo elements for making our lives easy :), so for a powerful application i'll take your advice and also i'll read more about CCXML 1.0.

---- This template will be very helpful, thanks a lot again ----

i'll be staying tuned.... and please send some greetings around!

Best regards!!!

Kave

kave

9/11/2007 1:38 AM (EDT)

hi Mike!

This template is very interesting, it has put my mind on other high -skilled CCXML level lol, but , i got some questions about it...

1- When every user calls , according to this template, every one of them initially would create a new conference?, i mean , when they get connected, the next transition is "getConfID" but they practically create a new conference and get joined or its the same conference where they get joined ??

2- how could i start the dialog for my three users when they are joined to the conference? i was thinking that if i create a var that contains the user numbers that are joined in the conference ( on my case, the three happy guys or girls), when this var is equal to 3, a VXML doc (that is the dialog) would be joined like a call leg or a inbound user, is that possible? also if when a user says "bingo" and n the dialog is running up, the VXML dialog would recognize this input (obviously with its previous "bingo" grammar word defined) as a normal input? in other words, this VCML doc would recognize and process input from these users as a normal one?

if i have a conference that was created for a first one user, i would like to join the next two ones, but if i want to do it in this way i should manage some var that detects if a conference has been created before and just joining the next two users, could i do it in this way?

Thanks again for all your supporting advices, i'l keep working on it....

have a nice day

Best
Kave

mikethompson

9/11/2007 11:38 AM (EDT)

Hi Kave,

The above script works like so:

The user calls in and is prompted to enter a conference ID. Once the ID is entered, the application will create a conference with the ID entered as "confname" (and assign it to the conferenceid variable defined as myConfID) and then join that user to the conference.

When the next caller calls in, he/she will also be prompted to enter the conference ID. Once this ID has been entered, the conference will again attempt to be created. Once the system recognizes the ID already exists, it will continue execution and join that user to the already existing conference.

Regarding how to get the VXML dialog to play to the conference participants, you will want to spawn a call out to an already existing application in your evolution account (via SIP). You are also correct in assuming your VXML dialog should have a grammar listening for bingo. The tricky part is you'll want to make sure your users stay quiet unless they have won. For example, an unspecified utterance could cause the VXML application to misbehave.

Now, in order to send the call out to the VXML dialog once 3 users are joined into the conference, you're going to have to employ the use of server-side scripting and a database. Specifically, just before each user joins the conference, you should let your database know a user has joined. Then, when you notice the database value is "3" (just before the 3rd user is about to join the conference), send the call over to the VXML script from that 3rd inbound session. Once answered, simply join that leg into the conference with the already existing participants.

This is by no means a simple application, and it will require some advanced CCXML/server-side logic, so be prepared to get your hands dirty. :)

Best,
Mike Thompson
Voxeo Corporation

kave

9/11/2007 3:26 PM (EDT)

hi Mike!!!

Thanks again!!!

Ben,( a pal from voxeo support tickets) told me that i could join a VXML dialog like it was a call leg or a inbound call, i mean i suppose it is like...

<join id1="MyconfID" id2="bingoballs.xml" />?????

is it possible do it?

or is it more complicated than that?. The concept that you gave me it's like creating an outbound call for the 3rd user? am i right? i mean, when the 3rd user calls in, before joining him/her i call out the VXML dialog with the tag

<createcall dest="'bingoballs.xml'" name="bingob"/> ?????

then i would join him/her ti the conference and it would make that when i join this user, the other ones could listen the same dialog and they could participe like the 3rd one... am i right?

i know it needs server-side tools, but playing the VXML dialog for the users is the most complicated part of this, i think solving this part maybe i could finish this tricked application :), because anything else like data base verfication and others things are already done.

Mike, like always you have been so helpful!!!! thanks a lot!

send some greetings around!!!

Regards!!!

Kave

MattHenry

9/11/2007 6:00 PM (EDT)

Kave,

I believe what Mike was trying to put across was the fact that when playing a dialog to a CCXML conference, that we need to place a call to a seperate VXML dialog that is mapped in your account via the <createcall> element, and then <join> the call into the conference. One thing that you should keep in mind is that you ill want to keep this outbound call *within* the network in order to reduce latency, and as such, you should be dialing the SIP number associated with the VXML application, not the POTS number.

One thing that you may also want to consider when writing the VXML is to use hotword grammars, (see the <prompt> element), and to also use some conditional statements for the confidence level score to ensure that your caller utterances are indeed a 'true' match. Also, you may want to think about making the grammar a SRGS contruct, and to leverage the "GARBAGE" ruleref to increase accuracy.

Hope this helps,

~Matthew Henry

kave

9/12/2007 5:15 PM (EDT)

Hi again!

Well, i got it, thanks Matt!, now i'm trying to see how to join this VXML call in the conference (that address the VXML dialog that says the bingo balls) , i can't try it out on my pc beacuse my pc now is being updated, and i'm just right now developing the vxml files and the CCXML files. i've taken the template that mike has shown me before, so, in this part of my application i use a JSP variable named "k" that gives me the value of how many users are in the conference, when k=3 the VXML is being called, i just want to be sure that i'm doing the right thing, would it look like this....?
is the SIP expr well typed on "dest" attribute ?

thanks in avance, like always, send some greetings from Colombia around!

Best Regards,
Kave

....

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

<transition state="joinTheConf" event="dialog.exit" name="bevent">
<log expr="'*** JOINING CONFERENCE ***'"/>
<% if (k>=3%){ %>
<log expr="'*** Houston, everybody are in the building!!! ***'"/>
<join id1="call_0" id2="myConfID" entertone="'true'" exittone="'true'"/>
<createcall dest="'sip:bingoballs@...'" name="bingo" />
<%else{%>
<join id1="call_0" id2="myConfID" entertone="'true'" exittone="'true'"/>

<%}%>
</transition>

<transition state="joinTheConf" event="connection.connected" name="bevent">
<log expr="'*** VXML CALL DOC IS BEING CONNECTED ***'"/>
<join id1="bevent.callid" id2="myConfID" entertone="'true'" exittone="'true'"/>
</transition>


<transition event="connection.CONNECTION_FAILED" name ="bevent">
<log expr="'call failed'"/>
<exit/>
</transition>
....

MattHenry

9/12/2007 5:41 PM (EDT)

Hello Kave,

Your code looks alright, both in terms of the conditionals in the JSP, as well as the sip formatting: but the real test is going to be in seeing what happens when you call the app with the debugger open, of course. be glad to help out if you run into any trouble, but bear in mind that we aren't in the habit of providing JSP-specific support, or anything like that. In any case, let us know how things work out for you.

Regards,

~Matthew Henry

kave

9/12/2007 5:49 PM (EDT)

hi!!!

Ok Matt, i'll try it and let you know about it...

thanks for all , i'll keep in touch...

have a nice night...

best,
kave

selectronic

9/27/2007 8:45 AM (EDT)

hi sir,
I am looking for the integration of PHP with CCXML.
Is it possible to access the data base with both of them?

Please guide me regarding this.

Thank You.

mikethompson

9/27/2007 10:49 AM (EDT)

Hello,

What you're looking to do is not difficult from a logical perspective. Of course, if you're proficient in server-side scripting and databases, the entire project will be easy. :)

What you will want to do is collect all the information you need in the CCXML script, then issue a <send> to a server-side script (which must contain valid, well-formed CCXML). The server-side script you will have nested in your invoked document should be accessing the database and inserting the passed parameters (or doing a read, depending on what you're looking to do).

We actually have a great example of the <send> element with PHP on the following page of our documentation:

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

Give this a quick review, as well as checking out the <send> element in general, and I think you will be headed down the path to server-side righteousness.

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

Best,
Mike Thompson
Voxeo Corporation

Limiting Call length

| TOC

| Answering Machine Detection