tropowebapi tutorial - callerid

Tropo WebAPI Development Guide

| TOC

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 to array - specifically the id field:

{
   "session":{
      "id":"71d00a781cc47bf46712344740701fe1",
      "accountId":"46256",
      "timestamp":"2011-05-06T14:23:23.608Z",
      "userType":"HUMAN",
      "initialText":null,
      "callId":"148d0ca6cd8a2423d3016d4ea2c6f90b",
      "to":{
         "id":"5855550100",
         "name":"+15855550100",
         "channel":"VOICE",
         "network":"SIP"
      },
      "from":{
         "id":"4075550100",
         "name":"+14075550100",
         "channel":"VOICE",
         "network":"SIP"
      }
   }
}

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 have the ID of "Unknown".

On instant messaging or Twitter channels, the callerID will contain the sender's handle or ID. If you get a message on Twitter from @Tropo, id field would show as "Tropo".

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

Ruby
Node.js
PHP
Python

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 => "+19165550100")
  elsif (callerID == "3865550100")
    t.say(:value => "Sending you to Jason.")
    t.transfer(:to => "+14155550100")
  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("+19165550100");
	}
	else if(callerID == "3865550100") {
		tropo.say("Sending you to Jason.");
		tropo.transfer("+14155550100");
	}
	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("+19165550100");
}
elseif ($callerID == '3865550100') {
	$tropo->say("Sending you to Jason.");
	$tropo->transfer("+14155550100");
}
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("+19165550100")
	elif (callerID == '3865550100') :
		t.say("Sending you to Jason.")
		t.transfer("+14155550100")
	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.

Ruby
Node.js
PHP
Python
JSON

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

post '/index.json' do
  
  t = Tropo::Generator.new
  
  t.call(:to => "+14075550100",
        :from => "14071234569")
  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("+14075550100", null, null, "14071234569");
    tropo.say("Tag, you're it!");
	
    response.end(TropoJSON(tropo));

}).listen(8000);

<?php

require 'tropo.class.php';

$tropo = new Tropo();

$tropo->call("+14075550100", array(
	"from" => "14071234569"
));
$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("+14075551212", _from = "14071234569")
	t.say("Tag, you're it!")
	
	return t.RenderJson()

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

{
   "tropo":[
      {
         "call":{
            "to":"+14075550100",
            "from":"14071234569"
         }
      },
      {
         "say":[{"value":"Tag, you're it!"}]
      }
   ]
}

For transfers, you can similarly set callerID:

Ruby
Node.js
PHP
Python
JSON

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 => "+14075550100",
            :from => "14071234569")
  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("+14075550100", null, null, "14071234569", 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("+14075550100", array('from' => "14071234569"));
	
$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("+14075551212", _from = "14071234569")

	return t.RenderJson()

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

{"tropo":[
      {
         "say":[
            {"value":"Transferring you now, please wait."}
         ]
      },
      {
         "transfer":{
            "to":"+140745550100",
            "from":"14071234569"
         }
      }
   ]
}

Text messages must have a callerID/senderID attached, so we can't send "unknown". Instead, we use the first U.S. 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 U.S. phone numbers attached to your application. This is a carrier restriction: mobile carriers will drop any messages that contain a spoofed callerID.

For instant messaging and Twitter, you cannot set a senderID; these are set automatically to the IM or Twitter ID on your application. This is because IM networks & Twitter do not allow you to set the "from" address on a message: the message is always from the user who sent it.

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 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 550100, 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 911) 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 being 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.

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 in the same country.

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Call & Message Properties

| TOC

| SIP Headers - Retrieving & Sending