🛡️ ScamGuard — AI Voice Filter for Phone Calls

A voice AI agent that acts as a personal call screener. It answers all incoming calls, filters out scammers, and forwards legitimate calls to your real phone number.

Built with: Vapi · Claude Sonnet · ElevenLabs · Node.js

---

How It Works

Incoming call → Vapi number → Filter Bot (Claude)
                                   ├── scam keywords detected → Scam Trap Bot (wastes their time)
                                   └── normal call → forwarded to your real phone

Filter Bot — answers as a neutral secretary, listens to the caller, and decides within 1-2 exchanges whether it's a scam or a legitimate call.

Scam Trap Bot — plays a confused elderly woman named Natasha. Keeps scammers on the line as long as possible (up to 10 minutes) using deliberate confusion, mishearing, and distractions — without ever giving real data.

---

Features

• Real-time scam detection via keyword matching + LLM reasoning
• Seamless call forwarding for legitimate callers (they don't notice the bot)
• Configurable scam keyword list in server.js
• Full call transcript logging for scam calls
• Works with any phone number via call forwarding (Russian operators supported)
• Webhook-based architecture — stateless, easy to deploy anywhere

---

Tech Stack

Component	Service
Voice agent platform	Vapi
LLM	Anthropic Claude Sonnet
Text-to-speech	ElevenLabs
Server framework	Fastify (Node.js)
Recommended deploy	Railway / Render

---

Quick Start

Prerequisites

• Vapi account with API key and a phone number
• Node.js 18+

1. Install

git clone https://github.com/YOUR_USERNAME/scam-guard.git
cd scam-guard
npm install

2. Configure environment

cp .env.example .env

Edit .env:

VAPI_API_KEY=your_vapi_key
MY_PHONE_NUMBER=+7XXXXXXXXXX
PORT=3000

3. Deploy the server

# Railway (recommended)
npm install -g @railway/cli
railway login && railway init && railway up
railway domain  # → get your webhook URL

# Or local test via ngrok
ngrok http 3000

4. Run setup (once)

WEBHOOK_URL=https://your-app.up.railway.app/webhook npm run setup

This creates both assistants in Vapi and assigns the filter to your phone number.

5. Forward your number

Set call forwarding on your phone to the Vapi number:

**21*+1VAPINUMBER# (call)

→ Full guide for Russian operators: SETUP_RU.md

---

Project Structure

scam-guard/
├── server.js       # Webhook server — handles Vapi events, routes calls
├── setup.js        # One-time setup script — creates assistants, assigns number
├── package.json
├── .env.example
├── README.md       # This file
└── SETUP_RU.md     # Detailed Russian phone setup guide

Customization

Add scam keywords — edit SCAM_KEYWORDS array in server.js

Change trap behavior — edit SCAM_TRAP_PROMPT in server.js

Save transcripts to DB — add your storage logic in the end-of-call-report handler

---

Cost Estimate

Component	Cost
Vapi phone number	~$2/mo
Vapi usage (LLM + STT + TTS)	~$0.05–0.10/call
Forwarding to owner	~$0.01/min
Server (Railway free tier)	$0

---

License

MIT