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.

CCXML Event Listing

As stated previously, asynchronous events are the very backbone of the CCXML language. As such, having a complete understanding of what events can occur is crucial to becoming a good telephony developer. For this reason, we offer you a listing of all possible events that you are likely to run into when exploring Call Control XML. Only some events are clearly bound to a particular action, others can happen randomly, at any time, (such as a disconnection notification, for instance).

CCXML Events

ccxml.conference.joined

This event is sent if a call leg is connected to another call leg, in a locally bridged scenario, or by joining a real conference. It can also be seen as the notification that a <join> operation was sucessful. Note that for simple call leg to call leg conferencing, the conference identifier is the same as the call leg identifier.

Field	Explanation
`callid`	identifier of the call leg
`confid`	the conference identifier

ccxml.conference.unjoined

If a call leg leaves a conference initiated by an <unjoin> action, a termdigit, or is pushed out beacuse of a local bridge termination, this event will be sent. Please remember that at this point, the conference identifier might be of an instance which already ceased to exist.

Field	Explanation
`callid`	identifier of the call leg
`confid`	the conference identifier
termdigit	defines the termdigit used to unjoin a caller from a conference

ccxml.conference.created

If a conference has been created by the <createconference> action, then this event will serve as the notification for it. It also contains the conference identifier, which can then be used to join and unjoin call legs to a new object.

Field	Explanation
`confid`	the conference identifier

ccxml.conference.destroyed

This event will be sent if a conference is removed by the <destroyconfernce> action. At this point, all call legs formerly linked to the conference are guaranteed to be unjoined.

Field	Explanation
`confid`	the (former) conference identifier

ccxml.fetch.done

This event is sent if a <fetch> operation was successful, and the requested document is available to for use via the <goto> or <createccxml> elements.

Field	Explanation
`url`	contains the URL of the document which was fetched
`fetchid`	contains the identifier for the fetch operation

ccxml.authenticated

This event is sent if an authentication requested by the <authenticate> action was sucessful. Since this feature has a 'dummy' functionality right now, it will always be sent.

Field	Explanation
`n/a`	n/a

ccxml.loaded

This event indicates that the document has been loaded and parsed. Transitioning this event will give you a proper entry point if your session was not initiated by an incoming call.

The following example transitions this event to create an outbound call as soon as the document is loaded and parsed:


  <ccxml version ="1.0">
    <var name="state0" expr=" 'init' ">
    <eventhandler statevariable="state0">
      <transition state=" 'init' " event="ccxml.loaded">
        <createcall dest=" '1112223333' "/>
       <transition>
        ....
    </eventhandler>
  </ccxml>

Field	Explanation
`n/a`	n/a

Connection Events

connection.CONNECTION_ALERTING

On an incoming call, this event will be sent as part of the state machine for connections. At this stage, the call is not answered yet. It is not clear at this point to what extent this model will be kept in the final version of the specification. Yet the way the state machine is implemented on the Voxeo platform, the connection.* and call.* events are already useful and basically sufficient to react to changes in a call leg.

The connection events have a much higher granularity than the call events, thus, their purposes in development are different. While the event connection.CONNECTION_ALERTING here is very specific, the event call.CALL_INVALID can be used for a general handler if a call leg is not available anymore, regardless of whether this was due to a disconnection, or a simple call failure.

Field	Explanation
`callid`	the identifier of the call leg
`callerid`	the caller ID
`calledid`	the called ID

connection.CONNECTION_CONNECTED

This event is sent as soon as a call is answered. For an inbound call, it is the response to a successful <accept> operation. For outbound calls, it will be sent as soon as the call is answered.

Field	Explanation
`callid`	identifier of the call leg
`endpoint`	contains the SIP endpoint of the call as an IP address in an obfuscated form

connection.CONNECTION_CREATED

This event is to be sent when a connection is created.

Field	Explanation
`callid`	identifier of the call leg

connection.CONNECTION_DISCONNECTED

As soon as a (connected) call gets hung up, this event will be sent. The disconnection can either happen due to programmatic action, (such as encountering a <disconnect> action), or due to an endpoint terminating the call. Note that even if the callid is available, you cannot perform any new operations on it...as soon as a call is deemed to be invalid, the call object will be internally detached from its formerly associated session.

Field	Explanation
`callid`	identifier of the call leg

connection.CONNECTION_FAILED

This event is sent as soon as an attempt to connect a call fails. The classic scenario where this happens is an outbound call where the call destination returns a 'busy' or 'unavailable' status. Again, after this event, the call leg will be unavailable. The call failure reason is a well-defined string from the following list:

badnumber
busy
noanswer
rejected
timeout
unknown
unreachable

Field	Explanation
`callid`	identifier of the call leg
`error`	contains the reason for the failure

Call Events

call.CALL_CREATED

The same as for connection.CONNECTION_CREATED is also valid for this event type, since it is not clear how useful such a notification is at all.

Field	Explanation
`callid`	identifier of the call leg

call.CALL_ACTIVE

This event occurs parallel to the connection.CONNECTION_CONNECTED event. As soon as a call is answered, it is declared to be 'active'. As such, call and connection events can indeed happen at the same time, and have essentially the very same meaning, yet in different state models. It is up to the developer as to which one to choose. Please note that the order is not guaranteed at all, so do not count on call events being put into a sessions event queue before connection events or vice versa.

Field	Explanation
`callid`	the identifier of the call leg

call.CALL_INVALID

This is the universal signal that gets sent as soon as the call leg is no longer available. This can happen, for instance, due to a disconnection or a failed outbound call. Thus, this event is a convenient method to catch and handle the end of a session if it is bound to one call leg only, making state machines much simpler. And again, the call leg is not available at this point anymore, thus its identifier can only be used for external logic.

Field	Explanation
`callid`	identifier of the call leg

Dialog Events

dialog.exit

This event will be sent when a dialog finishes execution. In addition to the default fields available in the ECMASript event object, the VoiceXML platform may pass back variable name/value pairs via <exit namelist=""/>. The "returned" fields are a 1:1 mapping of the return values listed in the VXML namelist attribute.

Field	Explanation
`callid`	the identifier of the call leg
`dialogid`	the dialog identifier
`sessionid` (legacy field)	same as dialogid (legacy field)

dialog.started

This event simply confirms that the dialog was successfully established.

Field	Explanation
`callid`	identifier of the call leg
`dialogid`	the dialog identifier
`endpoint`	the (obfuscated) IP endpoint of the internal SIP connection, (if available)

Error Events

error.dialog.notstarted

This event is raised if, for whatever reason, a particular dialog couldn't be started. This can be due to an invalid URL for an audio file, or connectivity problems on the hosting server, (error 503, for example).

Field	Explanation
`callid`	identifier of the call leg
`reason`	printable error message
`error (legacy)`	printable error message (legacy)
`dialogid`	the dialog identifier

error.dialog.wrongstate

This event will occur when a dialog starts on an invalid resource, (e.g. a call leg which has not yet been answered)

Field	Explanation
`callid`	identifier of the call leg
`reason`	printable error message
`error (legacy)`	printable error message (legacy)
`dialogid`	the dialog identifier

error.fetch

This event will be sent if a <fetch> action failed, regardless of the reason for failure.

Field	Explanation
`url`	the URL which was passed to fetch the document from
`field`	the fetch identifier
`error`	printable error message

error.send

The CCXML <send> element can also be used to send events to targets which are externally located. In such a case, errors are indeed possible and will cause this event to be fired off.

Field	Explanation
`eventid`	identifier of the event that was supposed to be sent
`error`	printable error message

error.outofsync

In the current implementation of the Voxeo CCXML platform there are several rules of what operations can be performed at which time. For instance, it is illegal to use a <dialogstart> on a call-leg that is joined to an active conference. You must first <unjoin> from the conference. Imagine this as a series of actions where overlapping is simply not allowed. In such a case the 'error.outofsync' event will be thrown which, in a nutshell, indicates a funadmental flaw in an application and/or its state machine.

Field	Explanation
`callid`	the call leg on which the overlapping action occurred
`error`	printable error message

error.statemismatch

When an action is attempted where as the CCXML session itself is not in an appropriate state this event will be thrown. To illustrate, an attempt to <reject> a call leg which was already answered via the <accept> tag would undoubtedly throw this error. Again, if you encounter this in your application, it is an indicator of bad state machine coding. Naughty.

Field	Explanation
`callid`	the call leg on which the state collision occurred, (might be an empty value depending on circumstances)
`error`	printable error message

error.system

This event was introduced for general problems on the system level, which is admittedly ambiguous at this point. The system.error is sent, for instance, if a conference cannot be joined due to an internal misconfiguration.

Field	Explanation
`callid`	the call leg on which the error occurred (might be empty, depending on circumstances)
`error`	printable error message

error.document

Perhaps the most common error event -- this will occur when a general flaw is detected in an application document. For example, you will see this error if your XML was not well-formed, you have referenced an invalid ECMAScript expression, etc..

Field	Explanation
`error`	printable error message

User and System Errors

user.*

Custom events may be created/fired via the <send> element. Such events will always be prefaced by "user.". For example, sending the event "pancake" will cause the event "user.pancake" to be thrown. This naming syntax prevents collisions with existing events. The fields available in the event object of a "user" defined event are simply any name/value pairs submitted in the "namelist" attribute of the <send> element.

Field	Explanation
`user-defined`	user-defined

system.ping

CCXML sessions do have the possibility of getting stuck and becoming totally inactive and inaccessible for any application logic. Because of this, the Voxeo CCXML platform scans regularly for sessions which have not processed events or have no active calls running. If such a session is located, the system.ping event will be sent to it. This event must then be processed, otherwise the session will be shut down. This can be accomplished by always including the following snippet within your code:


      <transition event="system.ping">
        <log expr=" ' ** encountered a stalled cal, terminating the session ** ' "/>
        <exit/>
      </transition>

Field	Explanation
`n/a`	n/a

voxeo.cpa.result

This event is raised if the Voxeo Call Progress Analyzer , (CPA), event is available.

Field	Explanation
`callid`	the call leg with the CPA running
`type`	the called party type detected by the CPA (human/machine/beep/unknown)

ANNOTATIONS: EXISTING POSTS

esirkin

10/5/2006 2:54 AM (EDT)

I believe that syntax on ending <transition> should be </transition> under ccxml.loaded code example. Small nit...

jbassett

10/5/2006 5:25 AM (EDT)

Hello,

Good catch. I will make sure this gets fixed with the next round of DOC updates. Thanks again for pointing this out.

Jesse Bassett
Voxeo Support.

Event Handling Basics

| TOC

| D: Dialog Extensions