Robocalling and spam calls have been increasing in number over the last few years. Only in the US, there were 5.16 billion robocalls in 2023, an average of 19 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.

Using Lenny to block incoming spam calls

With SignalWire RELAY, we can build an application that 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. If you've been online for any amount of time, you've certainly encountered a CAPTCHA with "pick all of the pictures with a boat in it" on websites, for example. In this application, we ask the caller for the result of the sum of two random numbers to create a voice CAPTCHA.

If the incoming call is determined to be a robocall, it is sent straight to Lenny, 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 receiver can press ** on their keypad at any time and have the call instantly flagged as spammer and added to the database. That way, if an unwanted caller makes it through the CAPTCHA, they can still be banned.

This application uses node-persist, a simple file-based database, to keep track of flagged numbers and automatically reject calls. In a production application, you could use a different database such as PostgreSQL. Every phone number is saved, 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 be sent to have a chat with Lenny!

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 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's entertaining to listen to the 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.

Understanding the Code

Configuration

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 phone number (DID) you either purchased from SignalWire or verified with us to use as the FROM_NUMBER for the caller ID.

When signing up for the first time, your account will be 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.

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 run_docker.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.

You can test your application by calling the phone number you set up above and prepare for a simple math quiz... unless you are a robot!

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.

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.

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.

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

Sign up for a free account if you haven't already, you'll get $5 of free credit to try out Lenny, and join us in our Community Slack or Forum to connect with our team!