Stop spam calls with SignalWire Communication APIs and Node.js

How to create robocall protection and block spam calls

Solutions Architect Luca Pradovera

Section 1: The purpose

Robocalling and spam calls have been increasing in number over the last year. Only in the US, there were 165.1 million robocalls placed in 2020, an average of 14.1 per person, including children and people who do not have a phone!

SignalWire can help with its Relay technology, which allows us to easily create a robocall protection service.

The application

This application implements a call forwarding service with a voice CAPTCHA to determine if the caller is a human. If they are, it forwards the call to your phone number or the one you configured as the destination.

A CAPTCHA is an automated mechanism used to determine if the user of a service is a human or a machine. You have certainly interacted with visual ones such as "pick all of the pictures with a boat in it" on websites. In this application, we ask the caller for the result of the sum of two random numbers.

In case the incoming call is determined to be a robo-call, it is sent straight to Lenny (more on that below), and it is flagged as a spammer if someone tries to answer the CAPTCHA three times and fails. If the caller solves the CAPTCHA, their call gets forwarded to the configured private phone number for the DID.

Once the calls are connected, the user that received the call on his private number can press ** on his DTMF keypad at any time and have the call instantly flagged as spammer and added to the database. That way, if a human unwanted caller makes it through the CAPTCHA, they can still be banned.

The application uses node-persist, a simple file-based database, to keep track of flagged numbers and automatically reject calls. In a production application, you would maybe use a different database such as PostgreSQL. Every phone number is saved and remembered, so any callers who you want to receive calls from will automatically get through the second time they dial in. Spammers, on the other hand, will just be sent to have a chat with Lenny!

Remember, the application database is persistent, so you will have to remove the .node-persist folder in the directory to reset the database if you would like to test multiple times with the same number, or your call will be handled automatically as a spammer or a human depending on how you responded the first time.

What is Lenny?

Lenny is one of the most widely known anti-spam chatbots, designed to waste the time of telemarketers.

It is a set of connected audio files, spoken in a somewhat-Australian accent, that uses generic phrases such as "Are you there?" to lure a spammer into a long conversation about its "family", a supposed very smart daughter, or other topics. The average time wasted for a spam call is over 10 minutes, and it is also very fun to listen to recordings.

The bot itself is simple in its ingenuity, but setting up your own version has always been complicated due to needing some telephony infrastructure and a bit of logic. Signalwire Relay makes it easy to do.

Section 2: What you need to run the code


Start by copying the env.example file to a file named .env, and fill in the necessary information.

The application needs a SignalWire API token. You can sign up here, then put the Project ID and Token in the .env file as SIGNALWIRE_PROJECT_KEY and SIGNALWIRE_PROJECT_KEY.

You also need a DID (phone number) you either purchased from SignalWire or verified with us to use as the FROM_NUMBER for the caller ID.

If you sign up for the first time, your account will be start in trial mode, which you can exit by making a manual top up of $5.00. You can find more information on the Trial Mode resource page.

Other configuration entries can be found in config/default.json . The numberMap entry in particular is where you map your private numbers to the SignalWire DIDs you will use as your public number. In the same JSON file, you can find and change the text for the greeting and the sound files in use. Make sure you restart the application after making configuration changes.

Make sure you set up the DID in your SignalWire dashboard to use the Relay handler with the context you have in .env. The default is captcha.

You can find more information, including where to get your credentials and how to set up the phone number, in the Getting Started with Relay guide.

Running the application

If you are running the application locally, first load the .env file with set -o allexport; source .env; set +o allexport to load the environment variables, then run npm install followed by npm start.

It is simpler to run the application via Docker, by first building the image with docker build -t nodelenny . followed by docker run -it --rm -v ``pwd``/.node-persist:/app/.node-persist --name nodelenny --env-file .env nodelenny.

If you prefer, you can just run sh in your shell and the container will be built and started for you.

The docker container which runs this application can be found here. 

Testing it

Give a call to the phone number you set up above and prepare for a simple math quiz... unless you are a robot!

Section 3: The Code

The application is built around a fairly simple Relay Consumer pattern, but it is also easier to read the code directly on GitHub.

It is written in Node.JS, though the logic can be ported to other languages thanks to the Relay SDK.

Here is the link to the repository:

Let’s take a look at some of the more interesting parts of the code:

The CAPTCHA loop

The following code snippet is what implements the voice CAPTCHA, asking the caller for the result of a simple sum.

The in-call detection

This part of the application uses RELAY asynchronous methods to detect if a ** sequence has been pressed by the user while the call is active. If that happens, it means someone went through the CAPTCHA but is still someone we would rather not speak to.

Features used

This application utilizes many advanced capabilities of the SignalWire API, including call and DID routing, text-to-speech and speech to text. RELAY’s unique ability to execute DTMFdetection in-call make it easy to build interactive application that can be activated even while talking.

Deployment is made easy by RELAY’s ease of administration, and we recommend using a Docker container for your apps.

Section 4: Get started

Getting Started Guide

If you are looking for more information about using SignalWire, refer to our Getting Started guide.

Please feel free to reach out to us on our Community Slack or create a Support ticket if you need guidance!

Start a free trial

If you would like to test this example out, you can create a SignalWire account and space here.

Documentation and useful links

Relay Documentation

Relay Docker Images

Getting Started with Relay

SignalWire 101

Copyright 2021, SignalWire Inc.