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. Every Tropo call contains some SIP headers by default; carriers or SIP networks can define a wide variety of additional options as well. All included SIP headers are displayed in the Tropo logs, 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"

Sending SIP Headers

You can 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. 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:

require 'rubygems'
require 'sinatra'
require 'tropo-webapi-ruby'

post '/' do
  
  tropo = Tropo::Generator.new 
    
  tropo.say "Hello...transferring"
  
  tropo.transfer :to => username@sip.example.com',
                 :headers => {'x-callername' => 'Kevin Bond'}

end
var http = require('http');
var tropo_webapi = require('tropo-webapi');
 
var server = http.createServer(function (request, response) {

	var tropo = new TropoWebAPI();

	tropo.say("Hello...transferring");
	//to, answerOnMedia, choices, from, headers, name, on, required, terminator, timeout
	tropo.transfer('username@sip.example.com', null, null, null, {'x-callername' : 'Kevin Bond'}, null, null, true, null, null);

	response.end(TropoJSON(tropo));

}).listen(8000);
<?php

require 'tropo.class.php';

$tropo = new Tropo();

$tropo->say("Hello...transferring");
$tropo->transfer('username@sip.example.com', array('headers' => array('x-callername' => 'Kevin Bond')));
$tropo->RenderJson();

?>
from itty import *
from tropo import Tropo, Session

@post('/')
def index(request):

  s = Session(request.body)
  t = Tropo()

  t.say("Hello...transferring")
  t.transfer(to="username@sip.example.com", headers={"x-callername":"Kevin Bond"})
  return t.RenderJson()

run_itty()

Retrieving Individual SIP Headers

You'll also want to use a header sent to an app...in order to retrieve the information for a particular SIP header, you would use a method defined in one of the libraries to extract it. Below we'll show an example that retrieves the content from the custom header 'x-callername' (same one we set previously). Note that headers will be downcased, so if you need to access something like x-Test-Header, you would need to write it as x-test-header.

require 'rubygems'
require 'sinatra'
require 'tropo-webapi-ruby'

post '/' do

  t = Tropo::Generator.new
  v = Tropo::Generator.parse request.env["rack.input"].read

  getHeader = v[:session][:headers]['x-callername']
  
  t.say :value => "Hello " + getHeader
  
  t.response
end
var http = require('http');
var tropo_webapi = require('tropo-webapi');
 
var server = http.createServer(function (request, response) {  
    
    request.addListener('data', function(data){
            json = data.toString();
        });

        request.addListener('end', function() {

            var session = JSON.parse(json);
            var tropo = new TropoWebAPI();

            var getHeader = session.session.headers['x-callername'];

            tropo.say("Hello" + getHeader);

            response.end(TropoJSON(tropo));
        });
    
}).listen(8000);
<?php

require 'tropo.class.php';

$tropo = new Tropo();
$session = new Session();
$headers = $session->getHeaders();

$tropo->say("Hello, {$headers->x_callername}");

$tropo->RenderJson();

?>
from itty import *
from tropo import Tropo, Session

@post('/')

def index(request):
  
  s = Session(request.body)
  t = Tropo()
  
  getHeader = s.headers['x-callername']

  t.say ("Hello " + getHeader)

  return t.RenderJson()

run_itty(server='wsgiref', host='0.0.0.0', port=8888)

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.