| CCXML Voxeo 1.0 Development Guide | Home | Frameset Home |
| This is an ECMAScript expression which returns the id of the signaling incoming call leg that should be accepted in a string value. Note that the callid attribute is completely optional. If unspecified, the interpreter will accept using the id indicated in the current event being processed. |
| The <accept> element is used to explicitly accept and connect an incoming phone call |
| The expr attribute specifies the value to assign to the variable in question. This may be any valid ECMAScript value. |
| is the name of the variable to assign a value / expression to. |
| The <assign> element updates a local variable, (originally instantiated using the <var> element), with a new ECMAScript value. |
| Not Enabled The password attribute is an ECMAScript expression that denotes what password will be used for authentication with the Voxeo CCXML platform. |
| Not Enabled The server attribute simply designates an ECMAScript expression that defines the server to authenticate with. The value for this may be in URI format, or may contain an IP address with an optional port ID. |
| Not Enabled The userid attribute is an ECMAScript expression which defines what userid that the script will use to authenticate with the platform. |
| 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 version of this CCXML document (required). The only allowable version number is 1.0. |
| This attribute defines the XML namespace for any extension elements. This attribute is only required when a developer is using a voxeo-specific CCXML element extension, (such as 'voxeo:sendemail'). The only allowable value for this attribute is 'http://community.voxeo.com/xmlns/ccxml' |
| eventhandler, var |
| 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. |
| This attribute indicates the telephone URL which evaluates to the target for the outbound call. Not specifying this element will certainly cause a fatal, application-stopping error. |
| The name attribute is an ECMAScript expression that receives the outbound call leg's callid. |
| The timeout attribute specifies the amount of time to allow the call attempt to be made. If the call is not answered by the end of the duration of the maxtime attribute, then a 'connection.failed' event will be returned. |
| Determines when audio passes from second call leg to the first. If set to "TRUE," this will pass audio back to the originating call leg upon the first instance of media. In practice, this will typically mean the caller hears the standard "telephone ring" as if they had picked up a normal telephone and dialed the number. If set to "FALSE," there will be silence until an actual answer or callfailure is achieved. Note that this attribute is primarily used to detect that a phone has been answered in the event that the destination number does not send back the proper ISDN signal upon pickup, (common to some 800 numbers). |
| 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. |
| This attribute indicates the ID of any document referenced in a fetch operation, which is gathered with the fetchid. A sucessful fetch completion additionally provides a property whose value is the fetch ID of the document being fetched. |
| The sessionid attribute is an expression resolving to a platform-defined unique identifier that denotes the newly-instantiated thread of control. |
| Not Enabled The start attribute indicates an event object which is to be the starting event for the newly instantiated thread of control. This event will be the initial event sent to the document that has been started by this event, and the endpoint which originated this event will be inherited by the newly created thread of control. |
| 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 id attribute is an expression that grabs the unique, URI-formatted identifier for the conference. Not specifying this attribute will result in a fatal error. |
| The voxeo-confname attribute serves to allow developers an option to explicitly specify a name for the conference to create. Note that this attribute is entirely optional; the attribute can be declared with an empty value, or ignored altogether. |
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. |
| This attribute denotes the identifier indicating the conference to be destroyed. |
| 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. |
| This attribute is an expression which tells the dialog which call leg object it should be linked with. If unspecified, the default value of this attribute will equate to "_event.source", which means that the dialog instance will be associated with whatever call leg generated the last event. |
The dialogid attribute specifies the value of the session name used to identify the launched dialog. This value is used to reference dialog events, and is used as an identifier when the <dialogterminate> element is invoked. |
| This attribute indicates the space-separated list of variable names to be appended to the dialog URL as parameters. The variables will then be available as a variable/value pair in the resultant URI querystring that is sent to the server. |
| The src attribute indicates the URL of the VoiceXML dialog to be started. Also note that with the Voxeo dialog extensions, this can also be used to indicate playable audio files or dtmf tones to be output. In addition, this can also hold the value of a TTS string, and/or valid dtmf termdigit entries that can be accepted from the caller. Also allowed is a URI address specifying where a recorded audio stream is to be sent. See the 'Appendix D: Dialog Extensions' section for further details of this usage. |
| Specifies the MIME type of the requested resource. This value is used to determine and initiate the appropriate dialog system. Standard Values:
(see 'Appendix D' for additional details)
NOTE: The type attribute should not be used in conjunction with the prepareddialogid attribute. |
| 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. |
The dialogid attribute specifies a character string identifying the dialog. This dialogid will have been generated by <dialogstart> and stored in the ECMAScript variable identified by the "dialogid" attribute. |
| Set to "true" or "false" to specify if the dialog is immediately terminated. |
| 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 callid attribute specifies which call leg identifier should be disconnected when this element is encountered. However, this attribute is optional; if unspecified, then the call leg disconnected will be the the id indicated in the current event being processed. |
| The <disconnect> element is used to disconnect a specific call leg. When encountered, the <disconnect> element will send the 'connection.CONNECTION_DISCONNECTED' asynchronous event to the CCXML document when the operation has completed. |
| 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 cond attribute specifies an ECMAScript expression which can be evaluated to 'true' or 'false'. A condition must evaluate to 'true' in order for any enclosed operations to be performed. |
| 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’. |
| This attribute simply indicates the name of the eventhandler in question. |
This attribute denotes the variable name which is the <eventhandler> state variable. |
| ccxml |
| transition |
| The <eventhandler> element is the main parent element for the <transition> tag. Both of these in conjunction serve as the main event handling elements, (or state machine) of a CCXML document. Events received can be in response to a previous programmatic CCXML action, or they may be generated by an external source, (such as when an incoming call is received and needs to be answered). Additionally, user-defined events can be thrown via the <send> element. |
| Not Enabled The expr attribute should have an ECMAScript expression that indicating a message to be sent and caught. If unspecified, then the value returned by the expr will resolve to 'zero'. Note that this atrribute is currently non-functional, as the Voxeo CCXML browser does not return a 'ccxml.exit' event when the <exit> element is encountered. |
| Not Enabled The namelist attribute denotes the space-separated list of variable names to be sent as properties of the <exit> event. Note that this atrribute is currently non-functional, as the Voxeo CCXML browser does not return a 'ccxml.exit' event when the <exit> element is encountered. |
| 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 fetchid attribute is an ECMAScript expression which receives an internally generated unique string identifier to be associated with the completion event. This identifier can be tested by the fetch completion event handler to distinguish among several outstanding fetch requests. Every fetch request will receive a unique fetch ID, even requests for the same document. |
| The method attribute specifies the HTTP method to use when sending the request. If unspecified, then the value of ‘GET’, (default) is assumed, unless the submission of multipart/form-data is encountered, in which case the implied method will be ‘POST’. |
| The namelist attribute denotes the space-separated list of variable names to be sent along with the fetch. The variables will then be available as a variable/value pair in the resultant URI querystring that is sent to the server. |
| This attribute simply indicates the URI of the XML document to be fetched. |
| The synch attribute is an ECMAScript left-hand-side expression that is set to the fetch completion event. The specification of this attribute in a fetch element implies a blocking fetch, which will be executed synchronously. If this attribute is not specified, then the fetch is asynchronous by default. |
| 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. |
| This attribute indicates the ID of any document referenced in a fetch operation, which is gathered with the fetchid. A sucessful fetch completion additionally provides a property whose value is the fetch ID of the document being fetched. |
| 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 cond attribute specifies an ECMAScript expression which can be evaluated to 'true' or 'false'. A condition must evaluate to 'true' in order for any enclosed operations to be performed. |
| 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. |
| This attribute denotes whether parties in the conference will be able to hear the joining party. This attribute is useful for implementing an 'eavesdropping' functionality in a conferenced call. If 'half' is specified as the value, then the joined party will not be able to be heard by the rest of the parties in the conference. If set to 'full' then all parties will be able to hear the joined party. If not specified, this attribute defaults to 'full'. |
| This attribute indicates the first of the call leg identifiers or conference objects to <join> together in a conference. |
| This attribute indicates the second of two call leg identifiers or conference objects to <join> together in a conference. If both audio endpoints are call legs, then the interpreter will inherently be bridged together. However, if we have a call leg attempting to connect to a conference, (or vice-versa), then the call leg will be added into the conference automatically. Note that in the Voxeo implementation, two separate conferences maynot join together. |
The voxeo-entertone is used to play a tone or custom wav file to the conference particapents when another caller joins. Setting this to 'true' will play the default system beep, while setting it to 'false' will result in no alerting sound being played at all. The developer may also specfy a URL value that points to a user-defined wav file to be played instead of the default system beep. Note that this URL has a limitation of 250 characters maximum. |
The voxeo-exittone is used to play a tone or custom wav file to the conference particapents when another caller exits. Setting this to 'true' will play the default system beep, while setting it to 'false' will result in no alerting sound being played at all. The developer may also specfy a URL value that points to a user-defined wav file to be played instead of the default system beep. Note that this URL has a limitation of 250 characters maximum. |
The voxeo-termdigits attribute extension has been added to allow a user a method of disconnecting from a conference without hanging up the call. The value of this attribute specifies which DTMF key will disconnect the caller and return to the CCXML application:Note that specifying a value of '@' will allow any dtmf key to be pressed to exit from the conference. |
| 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 expr attribute is a required parameter for the <log> element that is an ECMAscript expression evaluating to a string to be logged. This string will be output in the Voxeo Realtime Logger when the <log> element is encountered. |
| Not Enabled The label attribute is an ECMAScript expression that returns a character string which is used as an identifier, or 'marker' indicating the reason for the <log> statement. |
| 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. |
| The endpoint attribute denotes a conference ID or a call ID which will be moved to the target session specified in the 'sessionid' attribute. |
| The event attribute specifies the event object to be sent to the target session to provide notifaction. The event endpoint may also be sent along with the event, if any. |
| The sessionid attribute indicates the thread of control to which the endpoint will be added. |
| 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. |
| Not Enabled The callid attribute specifies the id of the incoming call leg that should be redirected. This attribute is completely optional; if left unspecified, then the interpreter will redirect the signalling incoming call leg indicated in the current event being processed. |
| Not Enabled This attribute indicates the telephone URL which evaluates to the target for the outbound call. Not specifying this element will certainly cause a fatal, application-stopping error. |
| Not Enabled The reason attribute returns a user-defined ECMAScript string indicating the reason for the call being redirected. The value returned will be a standard HTTP status code, (i.e., "500" etc). |
| 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. Note that this element is unsupported at this time. |
| This attribute returns a string indicating the incoming call leg to be rejected. True to form, if this optional attribute is unspecified, then the current event id is used to indicate the callid to be rejected. |
| The reason attribute returns a user-defined ECMAScript string indicating the reason for the call being rejected |
| 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. |
| The src atttribute indicates the URI of the <script> to be executed. If unspecified, then the elements CDATA provides the inline content. |
| Not Enabled, (see below) A <script> element may occur in a <ccxml> element and in executable content. <transition> elements and <if> elements contain executable content. |
The delayattribute is used to specify a length of time that the <send> action should be delayed. Control is immediately returned to the application, but the event indicated in the <send> tag itself will be delayed, hence, there is no noticable application delay as this processes. Also be aware that the strict time formatting in the Voxeo mimplementation allows only milliseconds to be specified, (example: '1000ms'). Be aware that the queue for sending events must be maintained locally and any events waiting to be sent must be purged when the session that issued this request terminates. |
| This attribute denotes the type of event being generated. User defined events may include alphanumeric charaters, and the dot "." character, but nothing else. In addition, the first character must be an alphabetical character. Also note that case sensitivity does not apply for event type names. |
| is an ECMAScript left-hand-side expression that is the target for the event identifier. The unique identifier for the generated event is written to the target. If not present, the event's identifier is dropped. |
| The namelist attribute denotes the space-separated list of variable names to be <sent>. The variables will then be available as a variable/value pair in the resultant URI querystring that is sent to the server. |
| The target attribute denotes the user-defined identifier for the target CCXML document. Do note that it is totally legal for a CCXML program to send an event to itself! |
The <send> element allows a developer to direct user-defined events to the CCXML document. Note that all user-defined events must be prefixed by 'user.', for instance: |
| The cond attribute specifies an ECMAScript expression which can be evaluated to 'true' or 'false'. A condition must evaluate to 'true' in order for any enclosed operations to be performed. |
| The event attribute denotes the matching event type used to kick off the code contained within the <transition> element. Event types can be a user-defined, dot separated ECMAScript string of any length, or, (more commonly), it can indicate a platform-defined event type. Note that the '*' suffix is a wildcard, and will match zero or more characters of any event name. |
| The name attribute denotes the unique variable that is to receive the event indicated in the <transition> element. |
| Indicates the current possible state(s) of the eventhandler. |
| eventhandler |
| accept, assign, createccxml, createconference, destroyconference, dialogstart, dialogterminate, disconnect, else, elseif, if, join, reject, send, unjoin, var |
| 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. |
| This attribute indicates the first of the call leg identifiers or conference objects that hold the ID for the audio endpoint to separate. |
| The id2 attribute indicates the second of two audio endpoints to separate. if both endpoints are call legs, then the platform will inherently unbridge the two endpoints. But, if one of the endpoints is a conference, then the platform will remove the call leg from the conference. |
| The <unjoin> element is used to disconnect two audio endpoints which were previously connected with the <join> element. |
| The expr attribute specifies the value to assign to the variable in question. This may be any valid ECMAScript value. |
| The name attribute indicates the name of the variable. Any valid ECMAScript variable names are permitted as a value for this attribute. |
| 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 'body' attribute allows the developer to specify text to insert in the body of the email that is sent out when the element is executed. |
| The 'from' attribute allows the developer to specify a return address for emails sent through the 'voxeo:sendemail' element. Any valid email address is allowed, provided that it is parseable. |
| The 'to' attribute allows the developer to specify a return address for emails sent through the 'voxeo:sendemail' element. Any valid email address is allowed, provided that it is parseable. |
| The 'type' attribute defines the type of email to be sent to the maintainer of the CCXML application. If unspecified, then the resulting email message must be entirely user defined within the 'body' attribute. If, however, the 'type' is set to 'debug', then a whole host of debugging output is included in the body of the email, (very useful information to have for troubleshooting an application that goes belly-up when you aren't watching the realtime logger). |
| 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). |