CallXML 2.0 Development Guide

Home | Frameset Home

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

<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)" value="(tel|pstn|sip)" 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





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]


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








possible events

onerror type="badnumber"
The destination number is malformed, or returns a SIT tone.
onerror type="document"
Document was unable to be fetched for all the reasons web servers are unavailable 
onerror type="lineactive"
Trying to issue a telephony event such as <answer> on an already active line 
onerror type="telephony"
Unable to issue a telephony event such as <call> or <playaudio> or <ftp> 
onanswer
This event occurs when a session determines that a call has been answered. This element is used as a handler to transition an action or event in a CallXML script after executing a <call> action. See the onanswer element description for further details.
oncallfailure
This event occurs when the session determines that the attempted call cannot be completed because the dialed number is busy, a circuit is unavailable, a SIT tone was detected or other detectable call failure mode. The call is not automatically disconnected; rather, this element allows the developer to catch the event and attempt another action. See the oncallfailure element description for further details.


onmaxtime
This event occurs during user input if the user takes more time than is allowed by a maxTime attribute to input their entire response. See the onmaxtime element description for further details.








code samples
<call - parent>



<?xml version="1.0" encoding="UTF-8"?> 



<callxml version="2.0">



<block>

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

    <assign var="NumToCall" value="1112223333"/>



    <run value="Call_Target.xml"

  submit="*"

  method="get"

  var="NewSessionID" />



    <block label="HoldMusic"

           repeat="3">



       <playaudio format="audio/wav"

           value="RingTone.wav"

           termdigits=""/>



       <onexternalevent value="Success">

         <conference targetsessions="$session.EventsenderID;"/>

         <hangup/>

       </onexternalevent>



       <onexternalevent value="Busy">

         <text>

           All lines are currently busy.

           Please hang up and try your call again later.

         </text>

         <hangup/>

       </onexternalevent>



       <onexternalevent value="TimedOut">

         <text>

           There is no answer.

           Please hang up and try your call again later.

         </text>

         <hangup/>

       </onexternalevent>





    </block>



  </block>



</callxml>










<call_Target.xml - callerID - maxtime - value>



<?xml version="1.0" encoding="UTF-8"?>



<callxml version="2.0">

 <block label="B1">



<call value="$NumToCall;"

      maxtime="20s" callerID="6666666666"/>

   

    <onanswer>

      <sendevent value="Success"

                 session="$ParentSessionID;"/>

      <wait value="Unlimited"/>                      

    </onanswer>

  

    <oncallfailure>

      <sendevent value="Busy"

                 session="$ParentSessionID;"/>

    </oncallfailure>

  

    <onmaxtime>

      <sendevent value="TimedOut"

                 session="$ParentSessionID;"/>

    </onmaxtime>



  </block>



</callxml>










additional links
none
















            



                        
            
            
            
            
            
                
                
                
                
                
                
                
                
                
                
                
            








































  ANNOTATIONS: EXISTING POSTS


dvancamp



8/9/2006 9:38 AM (EDT)





This element requires the use of outbound dialing priveleges, which must be provisioned by voxeo support.














login







            




© 2011 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
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]
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

onerror type="badnumber"	The destination number is malformed, or returns a SIT tone.
onerror type="document"	Document was unable to be fetched for all the reasons web servers are unavailable
onerror type="lineactive"	Trying to issue a telephony event such as <answer> on an already active line
onerror type="telephony"	Unable to issue a telephony event such as <call> or <playaudio> or <ftp>
onanswer	This event occurs when a session determines that a call has been answered. This element is used as a handler to transition an action or event in a CallXML script after executing a <call> action. See the onanswer element description for further details.
oncallfailure	This event occurs when the session determines that the attempted call cannot be completed because the dialed number is busy, a circuit is unavailable, a SIT tone was detected or other detectable call failure mode. The call is not automatically disconnected; rather, this element allows the developer to catch the event and attempt another action. See the oncallfailure element description for further details.
onmaxtime	This event occurs during user input if the user takes more time than is allowed by a maxTime attribute to input their entire response. See the onmaxtime element description for further details.