Tropo is part of CiscoLearn More

Phone Number Intelligence through Tropo and Whitepages Pro

Posted on July 26, 2016 by Adam Kalsey

Customers often ask us how they can tell if a number can receive a text message. Or how to filter out robodialers from calling their numbers. Today’s tutorial shows how to use the Whitepages Pro API to control your Tropo phone number.

The Whitepages Pro Phone Intelligence API can be used to gather a large amount of information about a US phone number. Who owns it, which carrier it’s on, what type of line it is, and in many cases, even how long the phone has been active. By combining the Whitepages API with Tropo, you can change how your application routes calls based on who is behind that phone number.

Using their API is simple. You get an API key, include that key and the phone number in a query string, and get back a large JSON document containing tons of information about the phone number. Parse the JSON document and the data in your application.

Caller Quality

One of the datapoints returned by Whitepages is a reputation score of a phone number. This score is dervied by the volume of calls made by that number and nuisance reports by people. A score of 1-4 is returned, with 4 being the most suspicious and 1 indicating it’s a high-quality call. The raw data is returned as well, showing how many calls this number places, what sort of nuisances (telemarketer, survey, phishing, etc) have been reported on it, and how confident they are in the scoring.

Using this with Tropo to determine whether to answer a call or even to execute the rest of the app can be done by combining the score with Tropo’s reject() method. In your Tropo application, take the caller ID of the incoming call, look it up using the Whitepages API, and if the score is 3 or 4, reject the call, giving the caller a busy signal.

The following Ruby sample code shows how it would work. Lines 3-9 make the API call to Whitepages, in line 7 using the caller ID of the incoming call as the phone number to look up. Line 11 logs the reputation score. On line 12-14, if the score is 3 or more, it’s spam and the call is logged as spam and then rejected.

require 'rest-client'

wp_key = 'your-api-key'

response = RestClient.get 'https://proapi.whitepages.com/2.2/phone.json', {:params => {
  'api_key' => wp_key,
  'phone_number' => $currentCall.callerID
  }}
result = JSON.parse(String.new(response))

log "Phone reputation for #{$currentCall.callerID} is #{result['results'][0]['reputation']['level']}"
if result['results'][0]['reputation']['level'] >= 3 then
	log "Caller from #{$currentCall.callerID} is spam"
	reject
end

Place this code at the top of any Ruby application that gets incoming calls, and they’ll automatically be filtered for call quality.

Sending text messages to Landlines

Applications that send text messages to a list of users often have a problem with people who add landline or VOIP numbers to the list. Sending an message to these numbers can fail to get the message out, as carriers will attempt to deliver the text, even though the number can’t receive it. Instead, an application can check to see if the line is a mobile, and if not, call the number and play the message as text to speech. As an added bonus, this sample uses Tropo’s answering machine detection to leave a message if a voicemail or machine answers. And as an added added bonus, the sample checks the Whitepages API to see if the number is a valid, active number, capable of receiving calls or text messages.

The application is kicked off with a Tropo Session API call, passing in two variables: ‘to’ contains the number to dial, and ‘msg’ contains the message to text or speak. Lines 3-8 request the phone number info from the Whitepages API, using the ‘to’ variable as the lookup number in line 6. Line 10 logs the phone line type. Line 12 checks to see if the phone number ‘is_connected’ and if it’s not, will just skip calling or sending the message.

Lines 13-14 send the contents of ‘msg’ by text message if the number is a mobile phone. If it’s not a mobile, line 16 calls the number instead. Line 18 sets up answering machine detection, playing an introduction message, and then once Tropo’s determined that the call is answered by a human or that a machine is recording, lines 19 and 20 play the message.

require 'rest-client'

wp_key = 'your-api-key-here'
response = RestClient.get 'https://proapi.whitepages.com/2.2/phone.json', {:params => {
  'api_key' => wp_key,
  'phone_number' => to
  }}
result = JSON.parse(String.new(response))

log "%% Phone number #{$to} is #{result['results'][0]['line_type']}. Connected: #{result['results'][0]['is_connected']}" 

if result['results'][0]['is_connected'] || result['results'][0]['is_connected'].nil? then
	if result['results'][0]['line_type'] == 'Mobile' then
		message($msg, {:to => $to, :network => 'SMS'})
	else
		call $to, {
		   :callerID => $from,
		   :timeout => 30,
		   :machineDetection => {"introduction" => "Hello, this is an important message from your dentist. Please stay on the line."},
		   :onAnswer => lambda {
		       say $msg
		   }
		}
	end
end

Get Started

The Whitepages Pro API is priced per query, starting at 1¢ per query and has a free trial available. Visit the Whitepages Pro API documentation to get an API key and get started.

Leave a Reply