CCXML 1.0-W3C Development Guide

<createcall> element

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.

usage

attributes

dest	Data Type: (ECMAScript Expression)	Default: none - attribute is required
	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 voxeo platform follows the RFC's for both 'telephone' and 'sip' values, (RFC2806and RFC3261, respectively): <createcall dest="'tel:+18002223333'"...> (absolute syntax) <createcall dest="'tel:18002223333'"...> (exact syntax) <createcall dest="'sip:xxx.xxx.xxx.xxx'" ...> (sip address) Note: that developers who use the non-US datacenters are required to specify an E164-formatted dial string: tel:+[country code][number]
aai	Data Type: (ECMAScript Expression)	Default: Optional
	The aai attribute is populated with Application-to-Application Information from the call endpoint when the initial connection is successfully made. Note: this attribute is non-functional on the Voxeo hosted IVR network due to telco restricions.
callerid	Data Type: (ECMAScript Expression)	Default: Optional
	The callerid attribute is used for specifying a callerid value that will be sent to the destination of the outbound call. The voxeo platform follows the RFC's for both 'telephone' and 'sip' values, (RFC2806and RFC3261, respectively): <createcall callerid="'tel:+18002223333'"...> (absolute syntax) <createcall callerid="'tel:18002223333'"...> (exact syntax) <createcall callerid="'sip:xxx.xxx.xxx.xxx'" ...> (sip address) Note that UK developers are required to use E164 syntax for callerID spoofing: tel:+[country code][number]
connectionid	Data Type: (ECMAScript Expression)	Default: Optional
	The required connectionid attribute of the `<createcall>` element defines an ECMAScript expression that evaluates to a previously defined variable. The value of this variable is required to receive the identifier of the connection on which the outgoing call is attempted.
hints	Data Type: (ECMAScript Expression)	Default: Optional
	The hints attribute can be used to specify information used by the platform to configure the event processor. The value of this attribute should equate to an object that contains an array property of "headers" as shown in the following example: `<script> var Hints = new Object(); Hints.headers = new Object(); Hints.headers['x-mySipHeader'] = 'hello world'; </script>` Note: The `hints.headers` stores what headers to add to the sip request, and that only headers starting with an 'x-' prefix are sent.
joindirection	Data Type: (both/calltransmit/callreceive)	Default: Optional
	The joindirection attribute defines the media flow direction between a newly created connection and a pre-existing connection/conference/dialogid that is referenced by the joinid attribute. Allowable values and their descriptions are: both: Specifes a full duplex connection where the media flows in both directions. calltransmit: The new connection transmits media to the referenced connection/conference/dialog but does not receive any media streams. dialogreceive: The new connection receives media from the referenced connection/conference/dialog but does not transmit any media streams.
joinid	Data Type: (ECMAScript Expression)	Default: Optional
	Unsupported Attribute The joinid attribute allows the developer to specify an ECMAScript expression that serves as an identifier to a conference/connection/dialog ID that the new call will be joined to. At the time of this writing, this attribute is entirely unsupported on the Voxeo CCXML 1.0 platform, but we do plan on deploying full support for this feature in the coming months. When this does happen, announcements will be made in our public forums, and Voxeo newsletter. An existing methodology to work around this limitation is to simply workaround is to perform the `<join>` after the call is established, (call is in a "connection.connected" state).
timeout	Data Type: CDATA	Default: Optional
	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. The platform default is 60s, and a maximum of 180s is allowable.
voxeo-answer-on-media	Data Type: (true\|false)	Default: Optional (false)
	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).
voxeo-cpa-maskevent	Data Type: (human\|machine\|beep\|modem\|faxtone\|sit)	Default: 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\|beep\|modem\|faxtone\|sit)	Default: 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: Optional
	The 'cpa-maxsilence' parameter is used to identify the end of voice activity. When activity begins, CPA will measure the duration until a period of silence greater than the value of 'cpa-maxsilence' is detected. Armed with start and end timestamps, CPA can then calculate the total duration of voice activity. A value of 800 to 1200ms is suggested for this parameter.
voxeo-cpa-maxtime	Data Type: (ms)	Default: Optional
	The 'cpa-maxtime' parameter is the "measuring stick" used to determine 'human' or 'machine' events. If the duration of voice activity is less than the value of 'cpa-maxtime', the called party is considered to be 'human.' If voice activity exceeds the 'cpa-maxtime' value, your application has likely called a 'machine.' The recommended value for this parameter is between 4000 and 6000ms.
voxeo-cpa-runtime	Data Type: (ms)	Default: Optional
	The 'cpa-runtime' parameter specifies the maximum amount of time CPA should listen for events. If the 'runtime' exprires, CPA will return an "unknown" result. Therefore, 'cpa-runtime' should always be longer than the average answering machine outgoing message. We recommend a value of at least 15000-20000ms.

parents

none

children

none

code samples

<1.0 createcall-dest-callerid-connectionid-timeout> sample

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

<ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0">
<var name="inboundID"/>
<var name="outboundID"/>
<var name="initState" expr="'state1'" />

<eventprocessor statevariable="initState">
<transition state="state1" event="connection.alerting">
<log expr="'***** INBOUND CONNECTION ALERTING *****'"/>
<assign name="inboundID" expr="event$.connectionid" />
<accept connectionid="inboundID" />
<assign name="initState" expr="'state2'"/>
</transition>

<transition state="state2" event="connection.connected">
<assign name="initState" expr="'state3'"/>
<log expr="'***** CONNECTION.CONNECTED: INBOUND *****'"/>

<createcall dest="'tel:+14071112222'" callerid="'1112223333'" connectionid="outboundID" timeout="'30s'"/>

</transition>

<transition state="state3" event="connection.progressing">
<log expr="'***** CONNECTION.PROGRESSING *****'"/>
<assign name="initState" expr="'state4'"/>
</transition>

<transition state="state4" event="connection.connected">
<assign name="initState" expr="'state5'"/>
<log expr="'***** CONNECTION.CONNECTED: INBOUND *****'"/>
<join id1="inboundID" id2="outboundID" duplex="'full'"/>
</transition>

<transition state="state5" event="conference.joined">
<log expr="'***** CONFERENCE JOINED: INBOUND LEG TO OUTBOUND LEG *****'"/>
</transition>

<transition event="connection.disconnected">
<log expr="'***** CONNECTION.DISCONNECTED *****'"/>
<exit/>
</transition>
</eventprocessor>
</ccxml>

<10. createcall ani spoofing>

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

<ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0">
<var name="inboundID"/>
<var name="outboundID"/>
<var name="initState" expr="'state1'" />
<var name="phoneNumber" expr="'4071234455'"/>
<var name="ani" expr="'4075551234'"/>

<eventprocessor statevariable="initState">
<transition state="state1" event="connection.alerting" name="evt">
<log expr="'***** INBOUND CONNECTION ALERTING *****'"/>
<assign name="inboundID" expr="evt.connectionid" />
<accept connectionid="inboundID" />
<assign name="initState" expr="'state2'"/>
</transition>

<transition state="state2" event="connection.connected" name="evt">
<assign name="initState" expr="'state3'"/>
<log expr="'***** CONNECTION.CONNECTED: INBOUND *****'"/>
<createcall dest="'tel:1' + phoneNumber + 'callerid=' + ani" connectionid="outboundID" timeout="'30s'"/>
</transition>

<transition state="state3" event="connection.progressing" name="evt">
<log expr="'***** CONNECTION.PROGRESSING *****'"/>
<assign name="initState" expr="'state4'"/>
</transition>

<transition state="state4" event="connection.connected" name="evt">
<assign name="initState" expr="'state5'"/>
<log expr="'***** CONNECTION.CONNECTED: INBOUND *****'"/>
<join id1="inboundID" id2="outboundID" duplex="'full'"/>
</transition>

<transition state="state5" event="conference.joined" name="evt">
<log expr="'***** CONFERENCE JOINED: INBOUND LEG TO OUTBOUND LEG *****'"/>
</transition>

<transition event="connection.disconnected">
<log expr="'***** CONNECTION.DISCONNECTED *****'"/>
<exit/>
</transition>
</eventprocessor>
</ccxml>

additional links

W3C Specification

ANNOTATIONS: EXISTING POSTS

SSA_telespectrum

5/11/2010 4:47 PM (EDT)

Can we use String like 'abc' in the callerID?
Like <createcall dest="'tel:+14071112222'" callerid="'SSS'" connectionid="outboundID" timeout="'30s'"/>

jdyer

5/11/2010 5:21 PM (EDT)

Hello,

Setting this value to a string would result in the call being reject by most carriers. The varying 'pickyness' of carriers regarding callerID is why we always suggest that you e.164 encode any callerID (tel:+[ country code][number]). If you do want a callerID value mapped to a DID this is something we can do, but it is done at the carrier level, not the application level. If this is something you are interested in I can certainly have your account manager reach out to you to discuss this production offering further. Please let us know, as our team is most certainly standing by to be of service!

Regards,

John Dyer
Customer Engineer
Voxeo Support