Getting Call Detail Records

Posted on by No comments yet

Call Detail Records (CDR) are useful for gleaning information about your account’s voice and SMS traffic. They contain the callerID, the calledID, duration, channel/network, disposition and more. Tropo provides the CDR information in your account logs, and they are available from the web portal or through FTP (ftp.tropo.com). However, since these logs also contain lots of additional information about the application session, they can be a little overwhelming, and too verbose to easily search through manually. We’ll show you how a simple program can solve that issue, and provide you with the full code to run it yourself. Some modifications may be desired, but this walkthrough will provide a good starting point to get all of the CDRs, for every application in your Tropo account, for the last sixty days.

This tool requires knowledge of the command terminal, and Python (~2.7) needs to be installed in order to run it out of the box; no additional Python packages are required. It will use ftp.tropo.com (using your tropo.com username and password) to download your account log files.

To start, the app will download your log files to a local folder. It will only retrieve the logs that changed since the last time the tool was run (by checking the names and file sizes on the FTP server vs those already downloaded), which means the first time you run it, it will download all of your account logs, but each time after will be incremental. As an additional measure of security, the app uses FTPS.

After the log files are downloaded, the app will extract any logs that are compressed (archived logs are compressed, active logs remain plain text), parse the content for just the CDRs and then save them to their own files, without the extra Tropo log content.

Last, the app gives you the option to create a CSV file that contains all of the CDRs for every file collected; this method is a bit easier to read and process than the pure JSON CDRs. For every file downloaded, new CDRs will be appended to the CSV – unless you change the name of the CSV each time you run it, in which case only the new CDRs since the last run would appear in the CSV.

By default, the downloaded and extracted logs are placed into a “workinglogs” folder, while the final parsed logs are separated and placed into a “parsedlogs” folder; these can be changed in the code. We also include a prompt to ask for your Tropo username and password; you can hardcode it if you prefer.

Download or clone the complete app from our Github repository and once downloaded (assuming you already have Python installed), open up your terminal, navigate to your newly created file, and then type:

python ftp_cdr_tool.py myoutputCSV.csv

Phone Number Intelligence through Tropo and Whitepages Pro

Posted on by No comments yet

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.

DevOps with Cisco Spark: Follow your Tropo calls and SMS activity in real-time

Posted on by No comments yet

Integrating phone calls and SMS into your applications can be done in a snap with Tropo’s unique Scripting platform. A few lines of Javascript, PHP, Python, Groovy or Ruby, and you’re ready to run your phone call or SMS with a custom integration. Check this javascript snippet which implements a SMS subscription service. Try it yourself: text your email address to +1 414-882-4773

Try it by yourself at +1 438–448–3585 (text or call)

Now comes the time to support and grow your application: you want to track user activity in real-time and regularly check that your script executes properly on Tropo servers. To do this you’ ll have to create a custom dashboard, or dig into Tropo script logs (which can be detailed).

This is where Cisco Spark can help. We’ll show you how to push your Tropo script activity into a Cisco Spark room in (near) real-time. At the end of the article, you’ll have your INFO and DEBUG log levels pushed to Spark.

script

Tropo DevOps with Cisco Spark

If you care about DevOps, you’ve already connected most of your critical backend applications and strategic delivery processes to your favorite real-time messaging platform to raise alerts or to simply share information instantly with colleagues. Let’s extend your DevOps practices to Tropo in 3 steps:

“We’ll leverage the Cisco Spark API from Tropo’s Javascript Runtime. Note that the same principles apply to the all languages supported by the Tropo Cloud Platform (Javascript, Ruby, Python, PHP, and Groovy). As of now, example code is only provided in Javascript, and your contributions are welcome.”

1. Create a Spark incoming webhook

From the Spark Web client, create a room to be used exclusively for Tropo Logs or pick an existing room.

In the right hand panel of the Spark Room, click “add Integrations” and choose “incoming integration”.

“If you do not see the “incoming integration panel”, there’s good chance you are not in the Spark WEB client, but a Desktop or Mobile Spark client.”

Name your integration. Tis name will be used to publish messages to the Spark Room as new log entries are created by your Tropo script.

Finally, copy your webhook URI suffix.

1. Create a Spark incoming webhook

2. Add the Spark4Tropo Javascript library to your script

Copy/paste the Spark4Tropo.js code snippet at the top of your Tropo script.

Insert your Spark integrations suffix into the “YOUR_INTEGRATION_SUFFIX” placeholder. You may also want to identify your logs as they are pushed to the Spark room by changing the APPNAME.

2. Copy and customize the Spark4Tropo.js snippet

3. Enhance your Script Business Logic

Replace your script’s logs by the debug() and info() functions provided by the Spark4Tropo.js code snippet.

3. turn your logs to the provided log & debug functions

Now run your code again, and watch Tropo logs showing up in Spark as your script gets executed.

Future thoughts

You may create 2 Spark Rooms : one to follow Business activity (info logs in the example above), and the other one for Debugging Purposes (fine grained logs).

Spark4Logs configuration to send logs to several Spark Rooms

Tags: