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: Basic Event Handling

This lesson will step you through the process of handling events within CCXML. If you have not already completed Lesson 1, we suggest running our Hello World example first before tackling this tutorial.

In this lesson, we will:

Learn about events and event handling
Learn syntax for conditional expressions (if/then/else)

Learn how to answer and/or reject incoming calls

Step 1: creating our initial CCXML structure

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


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

Step 2: events

An "eventhandler" is actually a bundle of code pieces that are triggered on a certain event, state, or conditional expression. For right now we only care about events.


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

The order and "definition" of elements within an <eventhandler> block is critical -- CCXML will search sequentially through your document and trigger on the first match (even if there is a subsequent match that would be more accurate).

Transition elements contain the code for specific events you are looking to trigger. Our first <transition> takes care of virtually every event signaling an incoming call. Since many of your CCXML applications will want to answer the phone, let's see how that works:


<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING" name="evt">
      <log expr="'The called ID is ' + evt.calledid + '.'"/>
    </transition>
  </eventhandler>
</ccxml>

Note that the "event" attribute is not an ECMAScript expression, but a static value. As you can see, the <transition> element is another container -- this means that we can execute any number of elements once we have matched an event. So far, we are only logging the Called ID, but let's get our feet wet:


<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING" name="evt">
      <log expr="'The called ID is ' + evt.calledid + '.'"/>

      <if cond="evt.calledid == '8315551234'">
        <reject/>
      <elseif cond="evt.calledid == '8315557890'"/>
        <reject callid="evt.callid"/>
      <else/>
        <accept/>
      </if>

    </transition>
  </eventhandler>
</ccxml>

Here we see several advanced items: the complete if/elseif/else conditional structure is present, as well as the option to "accept" or "reject" the call (i.e., answer or not answer). Note the subtle difference between the first <reject> and second: you are able to specify the call leg to operate against. If the event came from the call leg itself, no specifier is needed -- the first <reject> works for this reason. The <accept> element fires an asynchronous event (as do most CCXML triggers), and will communicate to us later the result. If you are uncomfortable with the concept of asynchronous events, please poke the fat guy coding C++ in the cube next to you for an explanation.

Step 3: more events

Answering an inbound phone call is a two-step process, but still easy enough that anyone could understand. As we have already told CCXML to asynchronously fire an "accept" event, we now need a handler for that event:


<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING" name="evt">
      <log expr="'The called ID is ' + evt.calledid + '.'"/>

      <if cond="evt.calledid == '8315551234'">
        <reject/>
      <elseif cond="evt.calledid == '8315557890'"/>
        <reject callid="evt.callid"/>
      <else/>
        <accept/>
      </if>

    </transition>

    <transition event="connection.CONNECTION_CONNECTED">
      <log expr="'Call was answered.'"/>
      <disconnect/>
    </transition>

  </eventhandler>
</ccxml>

Our handler for finally answering the incoming call is very straight forward. We answer, log a debug message, and then immediately disconnect. Normal applications would hopefully do something snazzy before disconnecting the caller, but all that can be done later.

Just to be safe, our application needed one more event handler, this time capturing an "invalid call" situation. This will occur whenever an error, a rejection, or a disconnect has been tossed by CCXML. This will ensure that we properly clean up our session (provided that the session was itself triggered by an inbound call). You'll also note that we have added the Voxeo-proprietary <voxeo:sendemail tag into the mix; also check out the fact that we have specified the voxeo 'xmlns' attribute in the initial ccxml declartion. This is important, as otherwise, we will get a nasty parsing error.. Assuming that we fill in all the blanks so that we have a valid email address, we will then get an email notification whenever the 'call.CALL_INVALID' event is executed. Tres` cool, eh?


<?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"> 
  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING" name="evt">
      <log expr="'The called ID is ' + evt.calledid + '.'"/>

      <if cond="evt.calledid == '8315551234'">
        <reject/>
      <elseif cond="evt.calledid == '8315557890'"/>
        <reject callid="evt.callid"/>
      <else/>
        <accept/>
      </if>

    </transition>

    <transition event="connection.CONNECTION_CONNECTED">
      <log expr="'Call was answered.'"/>
      <disconnect/>
    </transition>

    <transition event="call.CALL_INVALID">
      <voxeo:sendemail to="'yourEmail@there.com'" 
                        from="'myApp@here.com'" 
                        type="'debug'" 
                        body="'We had an error! \n Time to panic! \n 
                            Flee the cities, abandon all hope! \n 
                            Or, just send this email to the support  
                            folks.'"/> 

      <exit/>
    </transition>

  </eventhandler>

  <log expr="'Application is starting ...'"/>
</ccxml>

As a final note, the <log> element at the very end of the application is outside the scope of our <eventhandler>. CCXML will initially execute all code in the application not contained in an eventhandler (thus, we would always see our "Application is starting..." message). Why you ask? Because events are fired asynchronously, code within an <eventhandler> block will not be executed until that specific event occurs; however, other CCXML elements are handled, and executed, sequentially. As we move forward, grasping this difference will become easier. For clarity, it is usually best to include your <eventhandler> block at the end of the document, but it is not a requirement (as shown above).

Download the CCXML source code!

What we covered:

Created an application with event handlers
Learned three kinds of events associated with incoming calls
Learned how to structure conditional statements
Introduced the concept of scope for CCXML
Learned about automated error logging via the <voxeo:sendmail> extension element

ANNOTATIONS: EXISTING POSTS

bigfun

5/3/2004 9:48 AM (EDT)

Funnier and funnier...
best-reading tutorial I have ever come acrosss....

poke the fat guy in the cube next to you -- indeeed!!!!

yliuvoxeo

3/16/2006 2:38 PM (EST)

What CCXML standard or which version of CCXML are you following?
Your example codes are well formed but not valid by CCXML v1.0 -- as I am using a syntax validating editor.
For example, <eventhandler/> is not even defined in CCXML DTD; it can not be used directly under <ccxml/>!

steve.sax

3/16/2006 2:56 PM (EST)

Hi there,

The documentation guide is based off of the specification from October 2002. Our Prophecy platform is indeed more compliant to the recent specification, should that be more to your taste. We have not gotten a chance to fully document the Prophecy CCXML platform as of this date, but it is forthcoming sometime this year.

Hope that this helps to clarify!

Steve Sax

sumitmaniktala

9/19/2006 3:01 AM (EDT)

Greetings,

I have a confusion, at some places in the code blocks on this page you have used evt.calledid and evt.callid. Are they same or different?

Regards,

Sumit Maniktala

MattHenry

9/19/2006 11:56 AM (EDT)

Sumit,

These are indeed different. 'callid' is the line itself that we are accepting or rejecting in this case, and 'calledid' designates the DNIS, (number that was dield to access the application).

Hope this helps to clear up the confusion,

~Matthew Henry

ravimalpani

12/30/2006 6:52 AM (EST)

Hi there
i am using a ccxml parser n i m facing problem using it.
How can i set event variables at real-time.
consider example

<if cond="evt.calledid == '8315551234'">
<reject/>
<elseif cond="evt.calledid == '8315557890'"/>
<reject callid="evt.callid"/>
<else/>
<accept/>
</if>

How can i set evt.calledid at real-time.Is there any method to pass arguments to parser at run time???!!!

VoxeoTony

12/30/2006 12:47 PM (EST)

Hi,

Can you give us more information on the parser you are using? I would like to be sure that you are not talking about processing to a server-side environment. In the case of the Voxeo browser the evt.calledid will be reached real time when the value (8315551234) is detected by the CCXML interpreter.

Looking forward to hearing from you.

Regards,

Tony

kave

9/1/2007 3:10 PM (EDT)

hi there,

this is about ....

<transition event="connection.CONNECTION_ALERTING" name="evt">
<log expr="'The called ID is ' + evt.calledid + '.'"/>

and you wrote...

"...So far, we are only logging the Caller ID..."

??????

thanks,

kave

mikethompson

9/1/2007 10:59 PM (EDT)

Hi Kave,

Just to clarify, the reason we said "so far, we are only logging the calledID..." is because this is only the 2nd tutorial in our documentation set, and logging callerID had not yet been illustrated. You should still be able to log the callerID within alerting if you really want to. :)

Best,
Mike Thompson
Voxeo Corporation

kave

9/2/2007 2:51 PM (EDT)

hi Mike!

You wanted to mean "CalledID" and in this tutorial said "CallerID", you have a typo mistake on the sentence "So far, we are only logging the CallerID..." check it out above , that was my confusion :P.

thanks pal, like always, you have been so kind to me!

Best,
Kave

voxeo.benb

9/2/2007 2:55 PM (EDT)

Thank you for pointing that out. I will pass this on to the Docs Maintainer, and he will update it for the next docs release.

-Ben Bohn
Voxeo Support

Intro to Event Handling

| TOC

Advanced Event Handling