Tropo is part of CiscoLearn More

SIP Headers - Retrieving & Sending

SIP headers are extremely useful - they provide a wealth of information about an incoming call, as well as enable you to define a variety of settings, such as toggling answerOnMedia on or off (which we show how to do later in this chapter). Every Tropo call contains some SIP headers by default; carriers or SIP networks can define a wide variety of additional options as well. Here's an example:

x-sbc-from:"\"username\"<sip:00001234567@192.168.0.101>;tag=2a648c6e",
x-sbc-allow:"BYE",
x-sbc-user-agent:"sipgw-1.0",
x-sbc-contact:"<sip:00001234567@192.168.0.101:16000>",
Content-Length:"247",
To:"<sip:9991234567@10.6.60.100:5060>",
Contact:"<sip:username@10.6.60.100:5060>",
x-sbc-request-uri:"sip:990009369991234567@66.190.50.10:5060",
x-sbc-call-id:"OWE0OGFkMTE1ZGY4NTI1MmUzMjc1M2Y3Y2ExMzc2YhG.",
x-sid:"39f4688b8896f024f3a3aebd0cfb40b2",
x-sbc-cseq:"1 INVITE",
x-sbc-max-forwards:"70",
CSeq:"2 INVITE",
Via:"SIP/2.0/UDP 66.190.50.10:5060;received=10.6.60.100",
x-sbc-record-route:"<sip:190.40.250.230:5061;r2=on;lr;ftag=2a648c6e>",
Call-ID:"0-13c4-4b7d8ff7-1c3c1b82-7935-1d10b081",
Content-Type:"application/sdp",
x-sbc-to:"<sip:990009369991427645@60.190.50.10:5060>",
From:"<sip:username@10.6.60.100:5060>;tag=0-13c4-4b7d8ff7-1c3c1b82-5c7b"

Retrieving Individual SIP Headers

Most of the time, just seeing a list of the headers isn't particularly useful - you want to use a header for a particular purpose. In order to retrieve the information for a particular SIP header, you would use getHeader. Below are some potential headers you could retrieve using getHeader - the first portion lists the header name while the second portion, after the colon, is sample data that would be returned. Note that headers will also be downcased, so if you need to access something like x-Test-Header, you would need to write it as x-test-header.

Here's an example showing how to actually use getHeader:

if (currentCall.getHeader("x-account-id"))
    {
    log("Your header value is " + currentCall.getHeader("x-account-id"));
    }
else
    {
    log("Your header value was not found");
    }
if ($currentCall.getHeader("x-test-header"))
    log "Your header value is " + $currentCall.getHeader("x-account-id")
else
    log "Your header value was not found"
end
<?php
if ($currentCall->getHeader("x-account-id")) {
    log("Your header value is " + $currentCall->getHeader("x-account-id"));
    }
else {
    log("Your header value was not found");
    }
?>
if (currentCall.getHeader("x-account-id")) :
    log("Your header value is " + currentCall.getHeader("x-account-id"))
else :
    log("Your header value was not found")
end
if (currentCall.getHeader("x-account-id"))
    {
    log("Your header value is " +currentCall.getHeader("x-account-id"));
    }
else
    {
    log("Your header value was not found");
    }

This blogpost explains how using x-account-id could enable you to determine the inbound network used to place the call.

Sending SIP Headers

You can also add custom headers when invoking a call or transfer method by using the headers attribute; make sure to include x- for your customer headers, e.g. test-header becomes x-test-header. As mentioned before, the header will be downcased, so if you needed to access x-Test-Header later, it would need to be written it as x-test-header. Here's an example (this activates answerOnMedia):

transfer("sip:alice@example.com", {
    headers: {"x-voxeo-aom":"true"}
});
transfer 'sip:alice@example.com', { 
    :headers => {'x-voxeo-aom' => 'true'}
    } 
<?php   
transfer('sip:alice@example.com', array( 
    'headers' => array('x-voxeo-aom' => 'true'))
    ); 
?>
transfer("sip:alice@example.com", {
    "headers": {"x-voxeo-aom":"true"}
})
transfer("sip:alice@example.com", [
    headers: ["x-voxeo-aom":"true"]
])

This by no means covers all the potential uses of headers, but should at the very least help explain how to start using them with Tropo.