Voice Introduction to CCXML, Part II

Introduction to CCXML, Part II

In case you missed it, you can still read the previous section of this article: Introduction to CCXML, Part I.

In Part II of the Introduction to CCXML, we will become more
familiar with the elements of the language and how they work
together to create call control applications.

CCXML Test Platform

To test my CCXML applications, I have been using the Voxeo Tech
Preview platform, which includes CCXML support. Voxeo was the first
company to support CCXML and is currently leading CCXML development.
It also helps that RJ Auburn from Voxeo is Editor of the CCXML
specification. You can sign up for a Voxeo Tech Preview account at http://techpreview.voxeo.com
to start working with CCXML platforms. As of this writing, Telera
had also developed CCXML support, and it will be available for
testing on its developer site in short order according to Srinivas
Penumaka, Product Manager for Telera’s DeVXchange.

Note: CCXML is still in a draft stage. The specification
will change. Also, the CCXML examples that you’ll see in this series
are tuned for Voxeo and may not work with another provider’s
implementation even though it conforms to the specification.

Basic CCXML elements

The root element, <ccxml>

Each CCXML application has a <ccxml> root element
that encapsulates the rest of the CCXML tags. It has one attribute, version,
which is required and whose value should be 1.0:

ex. <ccxml version="1.0">

Exiting a CCXML application with <exit>

By calling the <exit> element, the CCXML application stops
executing, discards all pending events and throws a ccxml.exit
event. If the CCXML application was started by another CCXML
application via the <createccxml> element, then the calling
application can catch this exit event, the return value of the expr
attribute and the values of the namelist attribute.

ex. <exit expr="0" namelist="state0"/>

Spawing a new CCXML application with <createccxml>

The <createccxml> element contains only one attribute, src,
which specifies the URL of the CCXML application to execute. Because
CCXML interpreters are non-blocking, both CCXML applications will
continue to execute at the same time. The called CCXML application
can return values with the <exit> element described above.

ex. <createccxml src="notification.ccxml/>

Queuing a CCXML application with <fetch>

In a multi-document CCXML application where callers may be
transitioned from one CCXML document to another, it’s a good idea.

ex. <fetch next="conference.ccxml"/>

Once a CCXML document has been loaded, it will throw a ccxml.fetch.done
event, which can be caught with a <transition> element. The
<fetch> element is usually used in conjunction with the <goto>
element, which transitions a user to another CCXML application.

Handling Events

<eventhandler>

When an event is triggered, the CCXML interpreter examines the
<transition> handlers to see if there is a matching trigger
for the event. The <eventhandler> element contains one
or more <transition> elements. The element can contain two
optional attributes:

  • id – the name of the eventhandler
  • statevariable – each <eventhandler> can be assigned a
    state variable that tracks the current state of a call. State
    variables will be covered later in the CCXML series.
ex. <eventhandler id="default" 
                  statevariable="state0">

It is unclear which events must be handled, so I would recommend
creating <transition> handlers for all event triggers listed
in Part I.

<transition>

Each <transition> element contains the code that will be
executed if the event attribute matches the current event
that is being processed. For example, the following transition
element will match the connection.CONNECTION_ALERTING event
when a caller dials up the CCXML application. From the caller’s
perspective, this state is when the phone is ringing and waiting to
be answered:

ex. <transition 
            event="connection.CONNECTION_ALERTING" 
            name="evt">

The <transition> element contains the following attributes:

  • state – optional; used when you want to control which event
    handler is triggered based on the current state in addition to
    the event.
  • event – required; one of the events defined in the list in
    Part I of the CCXML tutorial.
  • cond – optional; contains an ECMAScript expression that must
    evaluate as true for the handler to be executed.
  • name – optional; defines a local variable name that can be
    referred to within the <transition> element to access and
    set attributes of the call object.

The state, event, and cond attributes all
define the criteria that must be matched for the <transition>
element to be executed. This provides programmers with the ability
to create fine grained handlers based upon state variable, call
states and call conditions.

The <transition> elements will contain the majority of the
call control code. Below is a list of CCXML elements that can be
included within a <transition> element:

  • <accept> – answers a call
  • <createcall> – places an outbound call
  • <join> – conferences two call legs
  • <unjoin> – disconnects a two leg conference
  • <createconference> – joins multiple call legs
    together
  • <destroyconference> – breaks down a conference
    call
  • <dialogstart> – executes a VoiceXML dialog
  • <dialogterminate> – terminates the execution of a
    VoiceXML dialog
  • <send> – triggers a defined event
  • <disconnect> – ends the call
  • <assign> – assigns a specified values to a CCXML
    variable
  • <var> – defines a new CCXML variable
  • <if> – conditional statement similar to VoiceXML
  • <fetch> – pre-fetches a CCXML application and
    queues it for execution
  • <goto> – transitions the call to another CCXML
    application
  • <submit> – submits CCXML variables to another
    CCXML application
  • <exit> – stops the CCXML application

These elements will be covered in detail later.

Basic Call Control

Accepting calls with <accept>

The <accept> element answers an incoming phone call and is
usually called within a <transition> element, which is
answering to the connection.CONNECTION_ALERTING event.

ex.
<transition event="connection.CONNECTION_ALERTING"
            name="evt">
  <accept callid="evt.callid"/>
</transition>

The <accept> element contains the callid attribute,
which is optional, and specifies the call leg id that will be
accepted. If the callid is not specified, it will default to
the call leg id of the event that’s being processed. Setting the callid
attribute manually means that only a call with the specified id
will be answered. It is unlikely that you will ever set this
attribute manually. In the code snippet above, the callid
attribute is set to the callid value of the evt call
object, which is the call leg id of the object that is processing
the connection.CONNECTION_ALERTING event. This is essentially
the same as excluding the callid attribute.

Rejecting calls with <reject>

Of course, we don’t always have to <accept> the call, we
could have also rejected it based upon the caller’s phone number or
some other criteria by using the <reject> element. See the
<if> element in the Conditional/Control Statements
section below for an example.

Terminating a call with <disconnect>

The <disconnect> element does exactly what its name
implies–it terminates a call. You can specify the call leg to
terminate by specifying the call leg id in the callid
attribute. The attribute is optional.

ex. <disconnect callid="evt.callid">

Making an outbound call with <createcall>

The <createcall> element dials the phone number or SIP
address specified by the dest attribute. When the call is
connected, a connection.CONNECTION_CONNECTED event is sent,
which can be caught by a <transition> element. If the call
cannot be connected, a connection.CONNECTION_FAILED event is
sent.

ex. <createcall dest="'7035551212'"/>

Once an outbound call is connected, it’s common to execute a
VoiceXML dialog to interact with the caller. The code fragment below
is an example of two <transition> elements; the first one
places the call with <createcall>, the second one is executed
when the call is connected and executes a VoiceXML dialog with the
<dialogstart> element:

    <transition state="'init'" event="ccxml.loaded">
      <assign name="state0" expr="'dialing'"/>            
      <createcall dest="'7034769418'"/>
    </transition>

    <transition state="'dialing'" 
           event="connection.CONNECTION_CONNECTED">
      <assign name="state0" expr="'connected'"/>            
      <dialogstart src="'angie.vxml'"/>
    </transition>

Conditional/Control Statements

Controlling executing with <if>, <elseif>,
<else>

In fact, you might remember an earlier VoiceXML tutorial where we
controlled the dialog based upon the caller’s phone number. So in
conjunction with the CCXML <accept> and <reject>
elements, we could replicate this functionality in CCXML:

<transition event="connection.CONNECTION_ALERTING" 
            name="evt">
  <if cond="evt.calledid == '7035551212'">
    <reject/>
  <else/>
    <accept/>
  </if>
</transition>

The code snippet above is based in part on a tutorial located at:

http://techpreview.voxeo.com

If the ECMAScript code in the event attribute is evaluated
to true, then we reject the call; otherwise we accept it and pick up
the line.

Transitioning to another CCXML application with <goto>

The <goto> element contains only one attribute, next,
which contains the URL of the CCXML application that the caller will
be transitioned to.

ex. <goto next="conference.ccxml"/>

Submitting CCXML variables with <submit>

If it’s necessary to pass values to the next CCXML application,
you’ll want to use the <submit> element rather than <goto>.
Like <goto>, the next attribute contains the URL of the
CCXML application that will be executed. The namelist
attribute contains the list of variables contained in the current
CCXML application whose values will be passed to the next
application. The method attribute corresponds to the HTTP
method, which can be GET or POST (the default is GET).

ex. <submit next="conference.asp" 
            namelist="state calledid callerid"/>

Executing VoiceXML Content

Starting a VoiceXML dialog with <dialogstart>

The <dialogstart> element executes a VoiceXML dialog
specified by the src attribute. The element contains the
following attributes, all of which are optional except for src:

  • callid – same as the callid attribute defined for the
    <accept> element
  • src – must be a valid URL location of a VoiceXML dialog
  • type – MIME type; default is application/xml+vxml
  • name – same as the <transition> element
ex. <dialogstart src="'example2.vxml'"/>

The CCXML is non-blocking, so it does not stop executing the
CCXML application when a VoiceXML dialog starts. 

Stopping a VoiceXML dialog with <dialogstop>

In fact, you may want to pause or stop the VoiceXML dialog with a
<dialogstop> while the dialog is still executing. For example,
you might execute a VoiceXML dialog that plays on-hold music while
you try to conference in another party. When the other party
connects, you’d want to stop the music and announce that the other
party has joined the conference.

Conclusion

In Part II of the Introduction to CCXML series, we’ve learned the
basic elements that are used to handle events, execute VoiceXML
content, and control calls. In Part III, we will apply our knowledge
by creating a practical CCXML application.

About Jonathan Eisenzopf


Jonathan is a member of the Ferrum Group, LLC  which specializes in Voice Web consulting and training. He
has also written articles for other online and print publications
including WebReference.com
and WDVL.com. Feel free to send an
email to [email protected]
regarding questions or comments about the VoiceXML Strategy series,
or for more information about training and consulting
services.

Latest Posts

Related Stories