Detect Robocalls with Twilio Lookup and the Nomorobo Spam Score Add-on

March 25, 2019
Written by

bG2utclWVzVcVomibKtYGe99wJ0WvTItH9LDAeHYR5JP7XJ9EjaiFHv1608ZZ0FvkJRbXMHiP_y13RhJczikwUygbOuZ8jld-ag8FNLEqAIx-4g1ArTDbPLqTYvFXroUaH1y9l42

Twilio's CEO Jeff Lawson recently wrote about the history of robocalls and what we're doing to eliminate them. Until that happens, we can build a tool that will help us identify a robocall with a bit of Python, the Twilio Lookup API, and the Nomorobo Spam Score Add-on.

Set Up

In order to code along with this post you'll want to start with the following:

  1. Create a Twilio account
  2. Install Python 3
  3. Install the twilio-python helper library

Head to the Twilio Console and install the Nomorobo add-on. Look for the yellow logo and click through to "Install".

 

Nomorobo spam score - finally! No more robocalls!

Leave the name as nomorobo_spamscore and "Save" the Add-On.

Create a new file called nomorobo.py and add the following code.

# Download the helper library from https://www.twilio.com/docs/python/install
from twilio.rest import Client

# Your Account Sid and Auth Token from twilio.com/console
# DANGER! This is insecure. See http://twil.io/secure
account_sid = 'your_account_sid'
auth_token = 'your_auth_token'
client = Client(account_sid, auth_token)

phone_number = client.lookups \
   .phone_numbers('+19892008374') \
   .fetch(add_ons='nomorobo_spamscore')

print(phone_number.add_ons)

Replace the placeholder credential values

Swap the placeholder values for your_account_sid and your_auth_token with your personal Twilio credentials. Go to https://www.twilio.com/console and log in. On this page, you’ll find your unique Account SID and Auth Token, which you’ll need any time you use the Twilio API like this. You can reveal your auth token by clicking on the 'view' link:

Reveal your Auth Token in the Twilio Console

Please note: you should use environment variables to keep them secret before deploying to production. Check out how to set environment variables for more information.

python nomorobo.py

You should see output like this. A score of 1 means this is most likely a robocall.

{
  "status": "successful",
  "message": null,
  "code": null,
  "results": {
    "nomorobo_spamscore": {
      "status": "successful",
      "request_sid": "XRcd158617dd5716d123456foobar834d24",
      "message": null,
      "code": null,
      "result": {
        "status": "success",
        "message": "success",
        "score": 1
      }
    }
  }
}

If you get a response that says AddOn not found double check you have installed the Nomorobo AddOn in the Console.

How to tell if a phone number is a Robocaller

This code gave us some useful information, but let's create a reusable function so our application can be used as a handy script. In nomorobo.py, add the following function:

def is_robocaller(phone_number):
   """
   Args:
       phone_number (string): phone number in e.164 format

   Returns:
       boolean: 'True' if robocaller
   """
   spam_score = client \
       .lookups \
       .phone_numbers(phone_number) \
       .fetch(add_ons='nomorobo_spamscore') \
       .add_ons['results']['nomorobo_spamscore']['result']['score']

   return spam_score == 1

The possible values for score are 0 and 1. Next, replace the original phone_number = … and print statements in nomorobo.py with the following:

import sys
if len(sys.argv) < 2:
   print("""
   Please provide a phone number in E.164 format like this:
   $ python nomorobo.py +19892008374
   """)
   sys.exit(0)

input_number = sys.argv[1]
print(is_robocaller(input_number))

Make sure the function is_robocaller is defined before this code.

This includes a bit of error handling to make sure we provide a phone number when we run the script. Now our program can take a phone number as an argument and return its line type!

Try running it again with a new phone number, maybe something from your missed calls or your personal cell phone. Don't forget to put the number in E.164 format.

python nomorobo.py +19892008374 # real robocall I got today
# True

python nomorobo.py +14153466100 # CVS pharmacy
# False

🎉Ta da! Now we have a handy script we can use to identify robocalls.

What's next for using Lookup?

Maybe you want to filter calls in your call center or identify the line type (mobile vs. landline) of a phone number. With Lookup you can also prompt customers to add SMS (or voice!) based 2FA, clean up your database, or segment your users.

You may also be interested in:

Have you built something that takes advantage of Twilio Lookup? Let me know in the comments or on Twitter @kelleyrobinson.