Captcha for phone calls
Project status: Complete | Actively maintaining
Captcha for phone calls.
Captcha for phone calls.
Human call filter operates a separate phone number that verifies callers are human before forwarding the call to a VOIP number.
This technique is able to prevent robot spam calls.
A dashboard is also provided to view information about calls which have been made to the human call filter operated phone number.
When a call is made to the human call filter operated number the caller is asked a simple arithmetic question.
If the caller enters the correct answer, their call is forwarded to a VOIP number. If they answer the question incorrectly the call will be ended.
This allows you to trust that all calls which reach this VOIP number are from real humans and not spam bots.
A dashboard is provided which shows information about calls which have been made to the human call filter operated phone number.
The dashboard shows which numbers have placed calls:
The dashboard shows all the calls which have been received:
The dashboard shows the status of all the challenges which have been issued to users.
Human call filter uses environment variables for configuration:
DESTINATION
: Your VOIP address which verified humans will be forwarded to
This value will be in the format:
sername@sip_sub_domain.sip.us1.twilio.com
Replace username
with the username you set while configuring the
Twilio Elastic SIP Trunking Credentials List.
Replace sip_sub_domain
with the sub domain you set when configuring
the Twilio Elastic SIP Trunking domain name
CALLS_HTTP_PORT
: Port server responds to twilio call requests on,
defaults to 8000
DASHBOARD_HTTP_PORT
: Port server responds to internal dashboard request on,
defaults to 8001
DB_HOST
: Postgres connection hostDB_PORT
: Postgres connection port, defaults to 5432
DB_NAME
: Postgres database nameDB_USERNAME
: Postgres usernameDB_PASSWORD
: Postgres password, optionalHuman call filter plays audio clips during calls to communicate with the caller.
These clips are located in the ./audio-clips/
directory.
./audio-clips/
intro.mp3
: Played before a caller is asked a challenge to verify they
are humansuccess.mp3
: Played after a caller provides the correct answer to a
challenge and before they are forwarded to the VOIP phone addressfail.mp3
: Played after a caller provides the wrong answer to a
challenge and before the call is endedIt is recommended that you record your own versions of each of these clips. To ensure that callers who hear these clips know that they have reached your number.
Human call filter stores information about calls in a Postgres database.
Set the database related configuration variables (start with DB
) and run:
make migrate
This will run migrations on your database to setup the schema.
Human call filter uses Twilio to interact with phone calls.
Login to Twilio and setup the following components:
Navigate to the "Phone Numbers" dashboard.
First buy a number:
Then configure the number:
Webhooks, TwiML Bins, Functions, Studio, or Proxy
Webhook
http://<domain you deploy to>/call
and HTTP POST
TwiML
Enter CallDestination
for the "Friendly Name"
Enter the following text in the main box:
?xml version="1.0" encoding="UTF-8"?>
Response>
<Dial>Your destination number here</Dial>
/Response>
Make sure to replace Your destination number here
with your
actual phone number.
This will forward calls to your phone if an error occurs.
CallDestination
Navigate to the "Elastic SIP Trunking" dashboard.
First create a SIP trunk:
Next configure a login for the SIP trunk:
Finally configure a domain for the SIP trunk to serve requests from:
Human call filter will forward calls which it knows are from humans to a voice over IP number.
This lets you be confident that every call that comes into this number is a human and not a spam robot caller.
In order to receive calls with this VOIP number you must install and configure a VOIP application on your phone.
If you are using an Android phone I recommend you use the Zoiper VOIP application. Unfortunately I do not have experience with VOIP applications on iPhones so I can not make a recommendation.
On your phone in the VOIP application of your choice add a new VOIP account:
Set the host to:
sip_sub_domain.sip.us1.twilio.com
Replace sip_sub_domain
with the sub domain you set when configuring
the Twilio Elastic SIP Trunking domain name
Set the username to the username you set while configuring the Twilio Elastic SIP Trunking Credentials List
Set the password to the password you set while configuring the Twilio Elastic SIP Trunking Credentials List
With your new VOIP number configured you can now begin receiving VOIP calls on your phone.
A Kubernetes Helm chart is located in the deploy/human-call-filter/
directory.
The Kubernetes deployment provided is fairly opinionated.
It makes a few assumptions:
If any of these assumptions are not true for your deployment situation you may have to edit the Kubernetes deployment provided.
Edit the deploy/human-call-filter/values.yaml
file and change the
following options:
gcp.cloudsql.connectionName
: The connection name for your GCP
CloudSQL instanceThen set the DESTINATION
, DB_HOST
, and DB_PASSWORD
environment
variables to their production values.
To deploy run the following in the repository root:
git submodule init --update
./deploy/k8s-deploy/k8s-deploy deploy
A Docker image is published which runs the human call filter server.
The image is named noahhuppert/human-call-filter
and is published to the Docker hub.
The container tag is the source code git commit the image was built with. This will change with every release. Check the Docker hub for the latest tag.
Run the image by setting all the required environment variables and exposing the correct port for call HTTP traffic.
Make sure to not expose the dashboard HTTP port, as this shows private information without requiring authentication. Instead the dashboard port should be accessed via a private network.