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: 30s
The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
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


Note that developers who use the non-US datacenters are required to specify an E164-formatted dial string:



tel:+[country code][number]


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


SethStern



4/29/2011 10:23 AM (EDT)





G'day!



The three of the four code samples that include a <call> element demonstrate the use of the "maxtime" attribute.  Unfortunately, the documentation fails to mention it.



Does it exist and, if so, what does it do?  It might limit the overall duration of a call, or perhaps just the duration after the call is answered.



Seth


voxeoshanesmith



4/29/2011 10:38 AM (EDT)





Hi,



I apologize for that oversight. The maxtime attribute has been deprecated in favor of "on" instead. I'll ping my documentation engineers to correct this. In the meantime, check out "on" and let me know if you have any questions regarding.



Thanks!

Shane Smith

Voxeo Support


SethStern



4/29/2011 3:30 PM (EDT)





Shane,



You're suggesting that the <on> element has replaced the "maxtime" attribute?  Instead of writing:



<call maxtime="30s" value="tel:+18005551212"/>

<on event="maxtime">

  <hangup/>

  </on>



the new script would be:



<call <on event="maxtime"/>  value="tel:+18005551212"/>

  <!-- 30 seconds, please. -->

  <hangup/>

  </on>



I don't think that's going to work,

Seth


VoxeoDustin



4/29/2011 5:47 PM (EDT)





Hey Seth,



Sorry, I believe he meant that the <maxtime> element was replaced by <on event="maxtime">. The code you pasted is correct:



<call maxtime="30s" value="tel:+18005551212"/>

 <on event="maxtime">

   <hangup/>

 </on> 



Let me know if you have any questions.



Regards,

Dustin Hayre

Solutions Engineer

Voxeo Corporation



[url=http://voxeo.com/prophecy]Download Prophecy 10[/url] | [url=http://docs.voxeo.com/prophecy/10.0/home.htm]Prophecy 10 Docs[/url]














login







            




© 2012 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: 30s
	The maxtime attribute indicates the maximum time that the CallXML browser should wait for digits before executing any repeat instances, if present.
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 Note that developers who use the non-US datacenters are required to specify an E164-formatted dial string: tel:+[country code][number]
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