Development Guides CallXML 3.0 CCXML 1.0-W3C VoiceXML 2.1 Search This Guide Chapters & Tutorials   Table Of Contents   Platform Overview   Creating an Application   Voxeo File Manager   Caching Techniques   Cache Manager API   Prophecy Porting Guide for CCXML   Learning CCXML 1.0 Hello World Basic Event Handling Advanced Event Handling Basic Error Handling Your First Dialog Advanced VoiceXML Dialogs Connecting Call Legs Outbound CCXML Token Dialing Multi-party Conferencing in CCXML 1.0 Using JSON, Send, and Foreach   A: All Things Audio CCXML Call Recording   B: Debugging Techniques Caching Techniques Debugging Techniques The Voxeo Real Time Logger Getting Support Help   C: Event & Error Handling Event Handling Basics CCXML Event Field Listing Conference Event Field Listing Connection Event Field Listing Dialog Event Field Listing Miscellaneous Event Field Listing Error Event Field Listing Sending Custom Events   D: Dialog Extensions Dialog Extension: audio/wav Dialog Extension: x-fetchdigits Dialog Extension: x-senddtmf Dialog Extension: x-recordaudio Dialog Extension: x-texttospeech   E: Client Side Scripting   F: Outbound Dialing Postdial How-To Limiting Call length Duplex Conferencing Answering Machine Detection Advanced Answering Machine Detection Conferencing with Whisper Unjoin via termdigit ANI and DNIS   G: Send Element & HTTP requests   H: Passing in Application Parameters Passing Variables to VXML   I: CCXML 1.0 Objects   J: Session and Application Variables Elements Element Summary  accept  assign  authenticate  cancel  ccxml  createcall  createccxml  createconference  destroyconference  dialogprepare  dialogstart  dialogterminate  disconnect  else  elseif  eventprocessor  exit  fetch  foreach  goto  if  join  log  merge  meta  metadata  move  redirect  reject  script  send  transition  unjoin  var  voxeo:sendemail   The <accept> element is used to explicitly accept and connect an incoming phone call The <assign> element updates a local variable, (originally instantiated using the <var> element), with a new ECMAScript value. Not Enabled The <authenticate> element is used to determine whether the Voxeo CCXML platform is to trust the webserver serving up the CCXML document itself. The attributes of this element contain the login credentials needed to be validated by the hosting platform. At this time, the requirement of having an <authenticate> tag within the CCXML document is not required, but this may change in the future. The <cancel> element provides a quite useful method of stopping a CCXML event timer, (such as an event that is in a pending state from a <send> directive that has a delay specified. When executed, this element will remove any pending event from the event queue of the invoking CCXML session in question. Note that if a delay timer has already expired when this element is fired off, an error.notallowed will be thrown to the event queue instead. Also be aware that this 'cancel' event can be sent to a local, or even a remote CCXML session. The <ccxml> element is the parent tag of any CCXML document, which encloses the entire contents of the document. Any child elements are executed in document order before the target <eventhandler> elements are reached in the document initialization. The <createcall> element is used for initiating a bridged transfer to the single outbound destination specified in the dest attribute. The tag is a 'fire and forget' element, meaning that the CCXML document is free to perform other tasks while the call is performed.  When the call attempt has been completed, either sucessfully or unsucessfully, an asynchronous event is sent back to the document, which can be caught via the <transition> element, thus allowing the developer to conference the call, or initiate a VXML dialog with the called party, etc. Note: This tutorial requires the use of outbound dialing priveleges, which must be provisioned by voxeo support. If you have not contacted us to get these permissions, click here to learn how you can get hooked up with this feature. The <createccxml> element is used to spawn another thread of control, which begins execution with the document identified by this element. This thread of control provides independent execution and an entirely separate variable space for the CCXML documents that it executes. Such independent threads are associated with one or more event endpoints; such endpoints are the only things capable of sending events to these independent threads of execution.Note that the new thread of execution has an entirely separate address space and lifetime. The <createconference> element is used to create a conferencing object, which is then used to create multi-party conferences. Once this has been created, the CCXML document can then add call legs (using the <join> element), subtract call legs, (using the <unjoin> element) form the conference, or bring down the conference object entirely, (using the <destroyconference> element). Note that any of the above operations will send an asynchronous event to the invoking CCXML document upon completion. The <destroyconferenece> element is used to tear down a conference object that was instatiated using the <createconference> element. Upon completion of this operation, an asynchronous event will be sent to the CCXML document notifying the application that the conference has indeed been destroyed. The <dialogprepare> element is used to prepare a VoiceXML dialog, or audio resource for execution via the <dialogstart> element. While the usage of this element as a precursor to a dialog exection is entirely optional, best practices dictate that this is included in CCXML front-end applications that utilize VoiceXML content for finer-grained control. Of course, the dialog will execute in a thread that is entirely seperate execution thread, and will not block the execution of CCXML events that occur during the session. When a dialog has been successfully readied for execution, a dialog.prepared event is thrown to the CCXML application. In the event that the dialog cannot be prepared for any reason, an error.dialog.notprepared event is sent to the CCXML session. Be aware that if the prepareddialogid attribute is specified and a conferenceid attribute was specified on the prior <dialogprepare> element, specifying a different conferenceid on the <dialogstart> element will incur an error.dialog.notstarted event being thrown to the CCXML session. The <dialogstart> element is used to launch a VXML dialog and associate it with a specific call leg. Said dialog executes on an entirely separate thread of execution from the invoking CCXML document, leaving the CCXML script in control to handle incoming events. When any VXML dialog has completed, best practices dictate that it should be 'torn down', (or, more properly, 'destroyed'). This is accomplished by using the <dialogterminate> element. When this tag is encountered and executed, a 'dialog.exit' event is returned to the CCXML layer of the application. The <disconnect> element is used to instruct the platform to disconnect a Connection.  A <disconnect> may also be used to abandon an outbound connection using <createcall> which has not yet entered the "connected" state.  If this occurs, it results in the generation of a "connection.failed" event.  If the connection was bridged when the <disconnect> request was sent, the platform must tear down all bridges to the connection, and send a conference.unjoined event to the CCXML document afterwards. The else element is used as the final logic constructor in an array of conditional statements. The content nested within the else element will get executed when all other if and elseif  cond attributes evaluate to ‘false’. The elseif element is used to specify additional content when all other else or if  statements equate to ‘false’.  When a series of if-elseif-else statements are encountered, the application will execute the first one which evaluates to ‘true’. The <eventprocessor> element replaces the <eventhandler> that was used in previous incarnations of the CCXML specification. It is identical in all respects to the deprecated <eventhandler> element, in that it is used as a container for the <transition> elements that drive the CCXML execution. Of course, only a single instance of this element may exist within any CCXML document. The <exit> element is used to stop execution of a CCXML program and it's thread of control. Any and all pending events are discarded, and application termination begins immediately. The <fetch> element, used in conjunction with the <goto> element, is used to transfer execution to a separate CCXML document. The <fetch> element allows for a pre-emptive fetch and parse of the target document to ensure that it is well formed and can execute before the <goto> ever executes. Voxeo Extension Element The <foreach> element is a Voxeo extension to the CCXML 1.0 specification, (which is being proposed for inclusion to the spec), that allows the developer to iterate through a set of array values, (such as the session.connections[] array). This allows a simpler shorthand than using pure ECMAScript to loop through array values. The <goto> element, used in conjunction with the <fetch> element, is used to transfer execution to a separate CCXML document. The <fetch> element allows for a pre-emptive fetch and parse of the target document to ensure that it is well formed and can execute before the <goto> ever executes. The <if> element, (in conjunction with the <else/elseif> elements), provides a method to utilize conditional logic expressions which allow the developer to change the control flow within the application based on variable values, or events. The <join> element is used to connected the audio of two "endpoints" in a CCXML script.  These endpoints can either be a conference object previously created with <createconference>, or a normal call leg object. The log element allows the developer to output debug messages to the Voxeo Logger. Generous use of log statements placed within code can greatly assist when tracking variable values, and errors that occur in the application. Unsupported Element The <merge> element is used to bridge two connections that are in a CONNECTED state at the network level, (severing the connections to the CCXML platform associated with those calls). If a <merge> operation fails for any reason, then a single error.merge event will be thrown which identifies both of the connections against which the merge was performed. Note that while this element is currently unsupported on the Voxeo platform, this is planned for inclusion on our network at a later date. When this feature is made available, announcements will be posted to the Prophecy User Forums, and via our Voxeo Developer Newsletter. The meta element functions in CCXML 1.0 as it does in HTML. It denotes meta information about the document, and its http headers. Note that cache-control is ignored; see our documentation on caching, and how to control it. This container element is used to allow the developer to specify information about the CCXML document for reference. Per the CCXML 1.0 specification, it is recommended that the Resource Description Format [RDF] be used in conjunction with the general metadata properties defined by the Dublin Core Metadata Initiative [DC]. Unsupported Element The <move> tag is used to add an event endpoint to an executing CCXML thread of control.  When an endpoint is added to a thread of control, events originating from that endpoint will be delivered to that thread's currently executing CCXML document. Note that while this element is currently unsupported on the Voxeo platform, this is planned for inclusion on our network at a later date. When this feature is made available, announcements will be posted to the Prophecy User Forums, and via our Voxeo Developer Newsletter. The <redirect> tag will redirect an incoming phone call to the specified destination telephony address URL.  This URL can be a VOIP endpoint, another phone number, etc. If a <redirect> is executed before the call is accepted the Prophecy platform will do a SIP redirect (302). Conversely, if executed after a call has been accepted a SIP refer will be executed. The <reject> tag is an element used for call authentication, in most cases. When encountered the CCXML document will reject an incoming phone call.  Rejected phone calls will go unanswered and may return a fast busy to the caller. A <script> element may occur in a <ccxml> element and in executable content. <transition> elements and <if> elements contain executable content. The <send> element allows a developer to direct user-defined events to the CCXML 1.0 document, or to an external I/O processors. The <transition> element is used to catch incoming asynchronous events. The first <transition> element encountered in the document order that matches up with a specific event will be the first one executed by the CCXML interpreter. The <unjoin> element is used to disconnect two audio endpoints which were previously connected with the <join> element. The <var> element is used to explicitly declare CCXML variables. All expressions must be valid ECMAScript expressions, assignable to variables with valid ECMAScript names. The 'sendemail' tag is a new extension element to Voxeo's arsenal of CCXML coolness. This tag allows you to programmatically send an email to a user specified destination. Additionally, this new element also allows you to output debugging information in the body of the email, which is a very useful 'watchdog' feature that allows you to be alerted via email whenever errors are encountered within the application. Also note that the 'xmlns:voxeo' attribute must be declared and mapped to the proper voxeo namespace, (see the 'ccxml' element listing for details).