Using outbound arbitrary SIP headers in Voice XML and Call Control XML

Outbound headers configured in siphdrtags.cfg can be sent as headers on outbound SIP messages. There are two mechanisms for accomplishing this depending on whether you are using CCXML and VoiceXML, or just VoiceXML. If you are using VoiceXML and not CCXML, you can specify the values of the outbound headers using the following functions that are automatically available within a VoiceXML application:

getInboundHeader(name, category)

Returns null if the header does not exist or if any part of the session.connection.protocol.category.name chain is null, otherwise returns the header object. name is the header name requested. category can be omitted and defaults to sip if not specified. You then need to specify the attribute (usually .value) of the returned object. For example:

     getInboundHeader('user-to-user').value

printObject(toPrint)

Prints out the attributes and associated values of a JavaScript object into a string and returns it. Useful for visualizing what is set on an object, or for seeing all available inbound headers with one log statement. For example:

     <log>Inbound headers are
     <value expr="printObject(session.connection.protocol.sip)"/>
     </log>  

clearOutboundHeaders()

Removes all values from the outbound array. This will stop them being used on subsequent VXML transfers and disconnects for the same call.

setOutboundHeader(name, value)

Multi-functional method for adding outbound headers either from the inbound headers or by the user supplying a value. name is the header name to add to the outbound headers in session.connection.protocol.sip.outbound value if specified is the value to assign to that header’s .value attribute. If not specified, the whole header object is copied from the inbound array.

Returns the outbound header object to which you can then assign additional attributes if you need to (this would be uncommon), or null if the outbound header could not be created due to invalid name or a null value coupled with no such named header being in the inbound array.

The outbound headers values can be specified manually by manipulating the session.connection.protocol.sip.outbound object itself.

The headers are not cleared between actions, so if a call is transferred and as a result hung up. Blueworx Voice Response sends whatever headers have been configured on both the TRANSFER and BYE messages unless you clear them.

Conversely, if you are using VoiceXML started from CCXML, the headers are instead handled by creating an object that is passed as the hints object on the relevant CCXML tag that initiates the message (such as createcall and send when sending ibmwvr.transfer). For example:

<ccxml version="1.0">
<script>function makeOutboundHeader(value){
                 var ret = new Object();
                 ret.value = value;
                 return ret;         }
</script>
   <eventprocessor>
 ...
      <transition event="dialog.transfer">
       <var name="target" expr="event$.URI"/>
       <var name="outbound" expr="new Object()"/>
       <var name="outbound['x-user-to-user']" expr="makeOutboundHeader('Example header value')"/>
       <var name="outbound['x-checksum']" expr="makeOutboundHeader('1234567890')"/>
       <log expr="'Outbound header x-user-to-user set as ' + outbound['x-user-to-user'].value"/>
       <send target="event$.connectionid" targettype="'connection'"
             name="'ibmwvr.transfer'" namelist="target" hints="outbound"/>
      </transition>
  ...
   </eventprocessor>
</ccxml>

In the above example, x-user-to-user and x-checksum must be defined in siphdrtags.cfg or the headers will not be sent out on the messages.

Please note that values set as described for VoiceXML-only transfers will appear on the dialog.transfer event but will not automatically be added to the headers, as that responsibility is taken by CCXML.