Tropo is part of CiscoLearn More

CallerID - Reading & Setting

CallerID is a fairly well understood concept - it defines who's contacting your application as well as what displays when your app makes outbound contact with someone. This section goes over what you can and cannot do in terms of both working with inbound callerID and setting outbound.

Reading caller ID

The callerID associated with a voice call or text message will appear in the session JSON, under the from array - specifically the id field:

{
   "session":{
      "id":"1aa06515183223ec0894039c2af433f2",
      "accountId":"33932",
      "timestamp":"2010-02-18T19:07:36.375Z",
      "userType":"HUMAN",
      "initialText":null,
      "callId":"abcdef743e245c265bc2c699b4112345"
      "to":{
         "id":"2125551212",
         "e164Id": "12125551212"
         "name":"unknown",
         "channel":"VOICE",
         "network":"PSTN"
      },
      "from":{
         "id":"4155559999",
         "e164Id":"14155559999",
         "name":"unknown",
         "channel":"VOICE",
         "network":"PSTN"
      },
      "headers":{
         "Content-Length":"247",
         "To":"<sip:2125551212@10.6.61.101:5060>",
         "Contact":"<sip:4155559999@10.6.63.104:5060>",
         "x-sid":"39f4688b8896f024f3a3aebd0cfb40b2",
         "CSeq":"2 INVITE",
         "Via":"SIP/2.0/UDP 66.193.54.18:5060;received=10.6.63.104",
         "x-sbc-record-route":"<sip:195.46.253.237:5061;r2=on;lr;ftag=2a648c6e>",
         "Call-ID":"0-13c4-4b7d8ff7-1c3c1b82-7935-1d10b080",
         "Content-Type":"application/sdp",
         "From":"<sip:4155559999@10.6.63.104:5060>;tag=0-13c4-4b7d8ff7-1c3c1b82-5d8c"
      }
   }
}

The id field strips formatting - so no parentheses or dashes - and for numbers outside the US, the callerID will be prefixed with the country code. Callers that have blocked their caller ID will typically have the ID of "Unknown".

The e164Id field is the caller ID with the country code always added.

Here's an example showing how to use callerID to customize a response per person:

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

post '/index.json' do
  
  v = Tropo::Generator.parse request.env["rack.input"].read
  t = Tropo::Generator.new
  
  callerID = v[:session][:from][:id]
  
  if (callerID == "4075550100")
    t.say(:value => "Sending you to Adam.")
    t.transfer(:to => "+14075551212")
  elsif (callerID == "3865550100")
    t.say(:value => "Sending you to Jason.")
    t.transfer(:to => "+16505553030")
  else
    t.say(:value => "You get nothing!")
  end
  
  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 callerID = session.session.from.id;
	
	if(callerID == "4075550100") {
		tropo.say("Sending you to Adam.");
		tropo.transfer("+14075551212");
	}
	else if(callerID == "3865550100") {
		tropo.say("Sending you to Jason.");
		tropo.transfer("+16505553030");
	}
	else 
		tropo.say("You get nothing!");	
		
    response.end(TropoJSON(tropo));
});

}).listen(8000); 
<?php

require 'tropo.class.php';

$tropo = new Tropo();
$session = new Session();

$from = $session->getFrom();
$callerID = $from["id"];

if ($callerID == '4075550100') {
	$tropo->say("Sending you to Adam.");
	$tropo->transfer("+14075551212");
}
elseif ($callerID == '3865550100') {
	$tropo->say("Sending you to Jason.");
	$tropo->transfer("+16505553030");
}
else
	$tropo->say("You get nothing!");
	
$tropo->RenderJson();

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

@post('/index.json')

def index(request):

	s = Session(request.body)
	callerID = s.fromaddress['id']
	t = Tropo()

	if(callerID == '4075550100') :
		t.say("Sending you to Adam.")
		t.transfer("+14075551212")
	elif (callerID == '3865550100') :
		t.say("Sending you to Jason.")
		t.transfer("+16505553030")
	else :
		t.say("You get nothing!")
		
	return t.RenderJson()

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

Setting callerID

When making a phone call, the callerID will be set to "Unknown" by default. You can override this by setting the from parameter on the call method. The callerID can be any number you like, but should be a real phone number - we explain why in the next section, Tips on Setting a Valid Caller ID.

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

post '/index.json' do
  
  t = Tropo::Generator.new
  
  t.call(:to => "+443069990432",
        :from => "+61491570157")
  t.say(:value => "Tag, you're it!")

  t.response
  
end
var http = require('http');
var tropo_webapi = require('tropo-webapi');

var server = http.createServer(function (request, response) {
	
    var tropo = new TropoWebAPI();
    
    //to, answerOnMedia, channel, from, headers, name, network, recording, required, timeout
    tropo.call("+443069990432", null, null, "+61491570157");
    tropo.say("Tag, you're it!");
	
    response.end(TropoJSON(tropo));

}).listen(8000); 
<?php

require 'tropo.class.php';

$tropo = new Tropo();

$tropo->call("+443069990432", array(
	"from" => "+61491570157"
));
$tropo->say("Tag, you're it!");

$tropo->RenderJson();
?>
from itty import *
from tropo import Tropo

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

	t = Tropo()

	t.call("+443069990432", _from = "+61491570157")
	t.say("Tag, you're it!")
	
	return t.RenderJson()

run_itty(server='wsgiref', host='0.0.0.0', port=8888)
{
   "tropo":[
      {
         "call":{
            "to":"+443069990432",
            "from":"+61491570157"
         }
      },
      {
         "say":[{"value":"Tag, you're it!"}]
      }
   ]
}

For transfers, you can similarly set callerID:

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

post '/index.json' do
  
  t = Tropo::Generator.new
  
  t.say(:value => "Transferring you now, please wait.")
  t.transfer(:to => "+443069990432",
            :from => "+61491570157")
  t.response
  
end
var http = require('http');
var tropo_webapi = require('tropo-webapi');

var server = http.createServer(function (request, response) {  
  
	var tropo = new TropoWebAPI();

	tropo.say("Transferring you now, please wait.");
	
	//to, answerOnMedia, choices, from, name, on, required, timeout
	tropo.transfer("+443069990432", null, null, "+61491570157", null, null, null, null);
	
	response.end(TropoJSON(tropo));

}).listen(8000); 
<?php

require 'tropo.class.php';

$tropo = new Tropo();

$tropo->say("Transferring you now, please wait");
$tropo->transfer("+443069990432", array('from' => "+61491570157"));
	
$tropo->RenderJson();

?>
from itty import *
from tropo import Tropo

@post('/index.json')

def index(request):

	t = Tropo()
	
	t.say("Transferring you now, please wait.")
	t.transfer("+443069990432", _from = "+61491570157")

	return t.RenderJson()

run_itty(server='wsgiref', host='0.0.0.0', port=8888)
{"tropo":[
      {
         "say":[
            {"value":"Transferring you now, please wait."}
         ]
      },
      {
         "transfer":{
            "to":"+443069990432",
            "from":"+61491570157"
         }
      }
   ]
}

Text messages must have a callerID/senderID attached, so we can't send "unknown". Instead, we use the first SMS-enabled phone number attached to your application as the senderID. While you can manually set the callerID to a specific number, it must be set to one of the SMS-enabled phone numbers attached to your application. This is a carrier restriction: many mobile carriers will drop any messages that contain a spoofed callerID.


Tips on Setting a Valid CallerID

  • Avoid setting the callerID to the same number you are calling. Setting it so it looks like you're calling a number from itself will yield unpredictable results. Some mobile carriers will send the call straight to voicemail. Some carriers will drop the call. Others will ignore the defined caller ID entirely.
  • Use a real phone number when setting callerID. While Tropo will allow you to set callerID to a single digit or even a letter, it's not recommended. Many carriers will ignore the defined caller ID or even drop the call all together.
  • In TV and movies, US phone numbers are often expressed with a 555 prefix. 555 is a special prefix that is reserved for use by the phone companies, so movies know that any numbers using 555 are always fictitious and cannot be called; many of our examples show 555 US phone numbers for this same reason. It also isn't recommended to use a 555 number as your callerID, however, as it too can cause unpredictable results. We've even seen a carrier strip one of the 5s and send the caller ID as +1212550100, apparently just for fun.
  • There are some numbers that Tropo will not allow you to set as callerID. These include numbers for emergency services (like the US's 911 and 999 in the UK) and numbers that may be used for illegal purposes.

Caller Name

It's not possible to set the name that appears on someone's callerID, as this isn't actually transmitted with the phone call at all - instead, every carrier maintains a database of phone numbers and the associated names. Carrier's subscribe to each other's databases, so an updated listing will eventually show up on all carriers. If you would like to set the caller name that appears on a caller ID display, contact support and provide your Tropo phone number along with the name you wish to display. We'll submit these to the carrier databases on your behalf, though it can take weeks or even months for the name to begin appearing on all carriers...which explains why your friend Dave calls you from his new phone number and shows up as defunct dating hotline instead.

Sending CallerID Internationally

Sending callerID across country lines can be problematic. There's no way to ensure that what you send actually shows up correctly on the other end - some countries and carriers use callerID formats that are incompatible with others, while some carriers are simply broken and can't accept callerID at all.

When sending a foreign callerID (for example a U.S. caller ID to a phone in the U.K.), the local carrier or even the user's handset may try and localize the number, displaying it as if it were a local call. In the U.S. to U.K. example, a caller ID of +14075550100 might be displayed as 0407 555 0100 on a UK phone.

Regulatory issues can also affect your callerID. Who is allowed to see and set callerID can vary by country; privacy rules can be ambiguous and up to carrier interpretation, leading to inconsistent callerID support among carriers even in the same country.