callxml elements

CallXML 3.0 Development Guide

<call> element

The Call element allows for new outbound calls to be placed to the specified address. The address is specified by the attribute value and is in URL format. Supported formats include:

tel:      classic phone number (See RFC 2896)
pstn:     same as "tel:", deprecated
sip:      SIP protocol address

Note: The usage of this element 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.



usage
<call answeronmedia="(true|false)" callerID="(tel|pstn|sip)" id="ID" maxtime="(m|s|ms)" test="CDATA" value="(tel|pstn|sip)" value-is="STRING" value-is-not="STRING" voxeo-cpa-maskevent="(human|machine|unknown)" voxeo-cpa-maskstop="(human|machine|unknown)" voxeo-cpa-maxsilence="(ms)" voxeo-cpa-maxtime="(ms)" voxeo-cpa-result="(human|machine|unknown)" voxeo-cpa-runtime="(ms)" voxeo-cpa-version="(2.0)">


attributes
answeronmedia Data Type: (true|false) Default: none - attribute is optional 
 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).
callerID Data Type: (tel|pstn|sip) Default: none - attribute is required
CallerID to present when placing the call. The list of allowable values declared for this attribute follow the same rules as the call value element/attribute combination, to wit:
"tel:"             classic phone number
"pstn:"          same as "tel:", deprecated value
 "sip:"            SIP protocol address


id Data Type: ID Default: Required
The id attribute is used to specify a unique conference identifier. The value is set to the session variable of $conferenceid; which is used  internally by the CallXML platform. 
maxtime Data Type: (m|s|ms) Default: none - attribute is optional 
Maximum amount of time to wait for the call to be answered. Time format strings are used for maxTime and maxSilence attributes, and in the <wait> tag.

The time string format is: 
<numeric value>[<optional qualifier>] | nolimit

The string begins with a required numeric value. The valid qualifiers are: 
m: minutes
s: seconds (default)
ms: milliseconds

Example: "45m 33s 117ms"

Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
test Data Type: CDATA Default: Optional
The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document.
value Data Type: (tel|pstn|sip) Default: none - attribute is required
The value for this attribute defines the URL describing the place to initiate a call to. An empty value will result in an error. Any value that does not begin with a valid prefix will be assumed to be a pure "tel:" number.

Valid URL values are:
"tel:"             classic phone number
"pstn:"          same as "tel:", deprecated value
 "sip:"            SIP protocol address
value-is Data Type: STRING Default: none - attribute is optional 
Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not Data Type: STRING Default: none - attribute is optional 
Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.
voxeo-cpa-maskevent Data Type: (human|machine|unknown) Default: none - attribute is optional 
The 'cpa-maskevent' parameter lists the CPA results that should throw an event.  This assures that only desired results, important to your specific application, will be acknowledged.  The value for this parameter should be a comma-separated list, any combination of the following:
human
 
machine
 
beep
 
modem
 
faxtone
 
*sit
  
voxeo-cpa-maskstop Data Type: (human|machine|unknown) Default: none - attribute is optional 
The 'cpa-maskstop' parameter lists the CPA results that, when received, will simply stop CPA from listening for further events. The value for this parameter should be a comma-separated list, any combination of the following:

human
 
machine
 
beep
 
modem
 
faxtone
 
sit
 
voxeo-cpa-maxsilence Data Type: (ms) Default: none - attribute is optional 
The cpa.maxsilence variable is the user-defined variable which designates the amount of time that the CPA should wait before it stops the human vs. machine analysis and returns the result of ‘human’. The setting for this variable is best set between 1000 and 2000ms.
voxeo-cpa-maxtime Data Type: (ms) Default: none - attribute is optional 
The user-defined cpa.maxtime variable determines the amount of time that the CPA should wait before returning a result of ‘machine’ to the application. The ideal setting of this variable should be in the range between  5000 to 7000ms.  Note that care must be taken when assigning the value to this variable, for if the callee’s initial utterance is longer than the maxtime value, the resultant value will be returned as ‘machine’.
voxeo-cpa-result Data Type: (human|machine|unknown) Default: none - attribute is optional 
This variable holds the resultant value of the human vs. machine analysis, which is determined when the call is answered. The possible results are:
human 
machine 
unknown
 
voxeo-cpa-runtime Data Type: (ms) Default: none - attribute is optional 
The user defined cpa.runtime variable is set to the desired length of time in which the analyzer should work before returning the final result. We will want to make certain that the time value set in this variable is longer than the added cpa.maxtime and cpa.maxsilence values, as well as setting this value to be longer than the ‘average’ length of an answering machine message. Most answering machine messages are no longer than 15000-20000ms in length, which would be a good range of values to insert for this variable.
voxeo-cpa-version Data Type: (2.0) Default: none - attribute is optional 
This attribute sets the Call Progress Analyzer version. This currently should always be cpa.version=2.0



code samples
<3.0 call - parent>
<?xml version="1.0" encoding="UTF-8"?> 

<callxml version="3.0"> 

<block> 
    <assign var="ParentSessionID" value="$session.ID;"/> 
    <assign var="NumToCall" value="4071112222"/> 

    <run value="call_Target.xml" 
  submit="*" 
  method="get" 
  var="NewSessionID" /> 

    <do label="HoldMusic" 
          repeat="25"> 

      <playaudio format="audio/wav" 
          value="Pulse.wav"/> 

     <on event="externalevent:Success">
        <log>*** EVENT = SUCCESS ***</log>
            <conference value="$session.EventsenderID;"/>
        <hangup/>
     </on> 

     <on event="externalevent:busy">
        <log>*** EVENT = BUSY ***</log>
      <prompt value="Sorry, but the number is busy"/>
     </on>


     <on event="externalevent:noanswer">
        <log>*** EVENT = NOANSWER ***</log>
      <prompt value="It looks like no one is home"/>
     </on>


     <on event="externalevent:unreachable">
        <log>*** EVENT = UNREACHABLE ***</log>
      <prompt value="Your called party is unreachable"/>
     </on>


     <on event="externalevent:rejected">
        <log>*** EVENT = REJECTED ***</log>
      <prompt value="Looks like your call recipient rejected the call"/>
     </on>


     <on event="externalevent:unknown">
        <log>*** EVENT = UNKNOWN ***</log>
      <prompt value="Received an unknown call failure. Panic at will"/>
     </on>

     <on event="externalevent:TimedOut">
        <log>*** EVENT = TIMED OUT ***</log>
      <prompt value="Max time for the call was reached, now disconnecting."/>
     </on>

    </do> 

  </block> 

</callxml> 

<3.0 call_target.xml - callerID - maxtime - value>
<?xml version="1.0" encoding="UTF-8"?> 

<callxml version="3.0"> 

<do label="B1"> 

<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666"/> 

   <on event="answer">
    <log> *** CALL ANSWERED IN CHILD SESSION*** works</log>
     <sendevent value="success" 
               session="$ParentSessionID;"/> 
      
            <conference value="$ParentSessionID;"/>
   </on>
 

    <on event="maxtime"> 
      <log>*** MAXTIME CALL EVENT CAUGHT IN CHILD SESSION *** </log>
      <sendevent value="timedout" 
                session="$ParentSessionID;"/> 
    </on>


    <on event="callfailure:unreachable">
      <log>*** UNREACHABLE EVENT CAUGHT IN CHILD SESSION ***</log> 
      <sendevent value="unreachable" 
                session="$ParentSessionID;"/> 
    </on>   


    <on event="callfailure:busy"> 
      <log>*** BUSY EVENT CAUGHT IN CHILD SESSION ***</log>
      <sendevent value="busy" 
                session="$ParentSessionID;"/> 
    </on> 



<!-- note that an 'anonymous' callfailure handler will catch all call failure events -->
<!-- that do not have their own specific handler. if the developer employs this soultion, -->
<!-- note that this handler must reside below all other handlers -->

    <on event="callfailure"> 
      <log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>
    </on> 


  </do> 

</callxml>

<3.0 call_target.xml - valueis>
<?xml version="1.0" encoding="UTF-8"?> 

<callxml version="3.0"> 


<do label="B1"> 

<!-- this will not be executed -->
<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666" value-is="A1"/> 

<!-- this will not be executed -->
<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666" value-is-not="B1"/> 

<!-- this will be executed -->
<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666" value-is="B1"/> 


   <on event="answer">
    <log> *** CALL ANSWERED IN CHILD SESSION*** works</log>
     <sendevent value="success" 
               session="$ParentSessionID;"/> 
      
            <conference value="$ParentSessionID;"/>
   </on>
 

    <on event="maxtime"> 
      <log>*** MAXTIME CALL EVENT CAUGHT IN CHILD SESSION *** </log>
      <sendevent value="timedout" 
                session="$ParentSessionID;"/> 
    </on>


    <on event="callfailure:unreachable">
      <log>*** UNREACHABLE EVENT CAUGHT IN CHILD SESSION ***</log> 
      <sendevent value="unreachable" 
                session="$ParentSessionID;"/> 
    </on>   


    <on event="callfailure:busy"> 
      <log>*** BUSY EVENT CAUGHT IN CHILD SESSION ***</log>
      <sendevent value="busy" 
                session="$ParentSessionID;"/> 
    </on> 



<!-- note that an 'anonymous' callfailure handler will catch all call failure events -->
<!-- that do not have their own specific handler. if the developer employs this soultion, -->
<!-- note that this handler must reside below all other handlers -->

    <on event="callfailure"> 
      <log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>
    </on> 


  </do> 

</callxml>

<3.0 call_target.xml - test>
<?xml version="1.0" encoding="UTF-8"?> 

<callxml version="3.0"> 


<do label="B1"> 

<!-- this will not be executed -->
<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666" test="1 = 2"/> 

<!-- this will not be executed -->
<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666" test="1 != 1"/> 

<!-- this will be executed -->
<call value="$NumToCall;" 
      maxtime="5s" callerID="6666666666" value-is="2 = 2"/> 


   <on event="answer">
    <log> *** CALL ANSWERED IN CHILD SESSION*** </log>
     <sendevent value="success" 
               session="$ParentSessionID;"/> 
      
            <conference value="$ParentSessionID;"/>
   </on>
 

    <on event="maxtime"> 
      <log>*** MAXTIME CALL EVENT CAUGHT IN CHILD SESSION *** </log>
      <sendevent value="timedout" 
                session="$ParentSessionID;"/> 
    </on>


    <on event="callfailure:unreachable">
      <log>*** UNREACHABLE EVENT CAUGHT IN CHILD SESSION ***</log> 
      <sendevent value="unreachable" 
                session="$ParentSessionID;"/> 
    </on>   


    <on event="callfailure:busy"> 
      <log>*** BUSY EVENT CAUGHT IN CHILD SESSION ***</log>
      <sendevent value="busy" 
                session="$ParentSessionID;"/> 
    </on> 



<!-- note that an 'anonymous' callfailure handler will catch all call failure events -->
<!-- that do not have their own specific handler. if the developer employs this soultion, -->
<!-- note that this handler must reside below all other handlers -->

    <on event="callfailure"> 
      <log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>
    </on> 


  </do> 

</callxml>



additional links
none
            



                        
            
            
            
            
            
                
                
                
                
                
                
                
                
                
                
                
            








































  ANNOTATIONS: EXISTING POSTS


asdf_ms



10/4/2007 3:03 PM (EDT)





data type specification, in the documentation, for the various vox-cpa timers states milliseconds (ms).  In fact, these values are in seconds.






mikethompson



10/4/2007 6:01 PM (EDT)





Hello,



Thank you for pointing this out.  I have alerted our "Keepers of the Documentation" to review and make the necessary changes.  The changes will be available as soon as the internal build for our doc set goes public.



Best,

Mike Thompson

Voxeo Corporation


voxeojeremy



10/4/2007 6:05 PM (EDT)





Hi there,





You definitely make a good point - the write-up should specify that by default, the values are in seconds.  The values in the example at the bottom of the page are in seconds.  I would like to point out that if you want to use milliseconds, all you need to do is append "ms" to the end of your numerical value (e.g.: voxeo-cpa-maxsilence="1200ms")





Regards, 



Jeremy McCall

Voxeo Extreme Support














login







            

© 2008 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site

answeronmedia	Data Type: (true\|false)	Default: none - attribute is optional
	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).
callerID	Data Type: (tel\|pstn\|sip)	Default: none - attribute is required
	CallerID to present when placing the call. The list of allowable values declared for this attribute follow the same rules as the call value element/attribute combination, to wit: "tel:" classic phone number "pstn:" same as "tel:", deprecated value "sip:" SIP protocol address
id	Data Type: ID	Default: Required
	The id attribute is used to specify a unique conference identifier. The value is set to the session variable of $conferenceid; which is used internally by the CallXML platform.
maxtime	Data Type: (m\|s\|ms)	Default: none - attribute is optional
	Maximum amount of time to wait for the call to be answered. Time format strings are used for maxTime and maxSilence attributes, and in the <wait> tag. The time string format is: <numeric value>[<optional qualifier>] \| nolimit The string begins with a required numeric value. The valid qualifiers are: m: minutes s: seconds (default) ms: milliseconds Example: "45m 33s 117ms" Note that if no qualifier is specified, an "s" qualifier is assumed. No combinations of qualifiers are allowed. If there is a need to specify an unlimited amount of time, simply use the key word "nolimit".
test	Data Type: CDATA	Default: Optional
	The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document.
value	Data Type: (tel\|pstn\|sip)	Default: none - attribute is required
	The value for this attribute defines the URL describing the place to initiate a call to. An empty value will result in an error. Any value that does not begin with a valid prefix will be assumed to be a pure "tel:" number. Valid URL values are: "tel:" classic phone number "pstn:" same as "tel:", deprecated value "sip:" SIP protocol address
value-is	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.
voxeo-cpa-maskevent	Data Type: (human\|machine\|unknown)	Default: none - attribute is optional
	The 'cpa-maskevent' parameter lists the CPA results that should throw an event. This assures that only desired results, important to your specific application, will be acknowledged. The value for this parameter should be a comma-separated list, any combination of the following: human machine beep modem faxtone *sit
voxeo-cpa-maskstop	Data Type: (human\|machine\|unknown)	Default: none - attribute is optional
	The 'cpa-maskstop' parameter lists the CPA results that, when received, will simply stop CPA from listening for further events. The value for this parameter should be a comma-separated list, any combination of the following: human machine beep modem faxtone sit
voxeo-cpa-maxsilence	Data Type: (ms)	Default: none - attribute is optional
	The cpa.maxsilence variable is the user-defined variable which designates the amount of time that the CPA should wait before it stops the human vs. machine analysis and returns the result of ‘human’. The setting for this variable is best set between 1000 and 2000ms.
voxeo-cpa-maxtime	Data Type: (ms)	Default: none - attribute is optional
	The user-defined cpa.maxtime variable determines the amount of time that the CPA should wait before returning a result of ‘machine’ to the application. The ideal setting of this variable should be in the range between 5000 to 7000ms. Note that care must be taken when assigning the value to this variable, for if the callee’s initial utterance is longer than the maxtime value, the resultant value will be returned as ‘machine’.
voxeo-cpa-result	Data Type: (human\|machine\|unknown)	Default: none - attribute is optional
	This variable holds the resultant value of the human vs. machine analysis, which is determined when the call is answered. The possible results are: human machine unknown
voxeo-cpa-runtime	Data Type: (ms)	Default: none - attribute is optional
	The user defined cpa.runtime variable is set to the desired length of time in which the analyzer should work before returning the final result. We will want to make certain that the time value set in this variable is longer than the added cpa.maxtime and cpa.maxsilence values, as well as setting this value to be longer than the ‘average’ length of an answering machine message. Most answering machine messages are no longer than 15000-20000ms in length, which would be a good range of values to insert for this variable.
voxeo-cpa-version	Data Type: (2.0)	Default: none - attribute is optional
	This attribute sets the Call Progress Analyzer version. This currently should always be cpa.version=2.0