# 🚀 Quick Start Guide - Voice AI with Twilio + LiveKit

## Complete Setup in 3 Steps

### Step 1: Configure LiveKit Telephony (One-Time Setup)

This configures LiveKit to accept calls from Twilio and route them to your agent.

```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/BackEnd/agent-starter-python
uv run python setup_telephony.py
```

**What this does:**
- Creates an inbound SIP trunk in LiveKit for your Twilio number
- Creates a dispatch rule to route calls to your agent
- Only needs to be run **once** (unless you change phone numbers)

---

### Step 2: Start the Backend (Python Agent)

The backend runs your voice AI agent that handles phone calls.

```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/BackEnd/agent-starter-python
uv run python -m src.agent dev
```

Or if you prefer using python directly:
```bash
python3 -m src.agent dev
```

**What you should see:**
```
============================================================
AGENT SERVER INITIALIZED
Agent is ready to accept connections
============================================================
```

**Keep this terminal running!** The agent needs to be running to handle calls.

---

### Step 3: Start the Frontend (React Web App)

The frontend provides a web interface to test your agent and make outbound calls.

```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/FrontEnd/agent-starter-react/agent-starter-react
npm run dev
```

**What you should see:**
```
▲ Next.js 15.5.2
- Local:        http://localhost:3000
```

**Keep this terminal running!** Then open http://localhost:3000 in your browser.

---

## 🎯 Testing Your Setup

### Test 1: Inbound Call (Phone → Agent)

1. Make sure backend is running (Step 2)
2. Call your Twilio number: **+14632175613**
3. The agent should answer and start talking!

### Test 2: Web Interface (Browser → Agent)

1. Make sure both backend and frontend are running (Steps 2 & 3)
2. Open http://localhost:3000
3. Click "Connect" to start talking to the agent in your browser

### Test 3: Outbound Call (Agent → Phone)

1. Make sure both backend and frontend are running
2. Open http://localhost:3000
3. Look for "Make Outbound Call" button
4. Enter a phone number (E.164 format: +1234567890)
5. Click "Call" - the agent will call that number!

---

## 📋 Quick Reference

### Backend Commands

```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/BackEnd/agent-starter-python

# Start agent (recommended - uses uv)
uv run python -m src.agent dev

# Or start agent (alternative - direct python)
python3 -m src.agent dev

# Setup telephony (one-time)
uv run python setup_telephony.py

# Check SIP trunk status
uv run python setup_sip_trunk.py

# Check dispatch rule status
uv run python setup_dispatch_rule.py
```

### Frontend Commands

```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/FrontEnd/agent-starter-react/agent-starter-react

# Development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start
```

---

## 🔧 Environment Variables

Both backend and frontend have `.env.local` files already configured:

### Backend `.env.local`
```
LIVEKIT_URL=wss://test-voice-bot-fd6qy6cu.livekit.cloud
LIVEKIT_API_KEY=APIVYTe7eb9UmEv
LIVEKIT_API_SECRET=bWhejV80AWmltf0C8kQ1FVral4g4QfI0A71JTCaUFs6A
ELEVENLABS_API_KEY=sk_503ae1d51ecbc66cb25843b74c7e722aac0cae4d5ac598ca
TWILIO_ACCOUNT_SID=ACd2fe6190353086ca693c87c0568dc90f
TWILIO_AUTH_TOKEN=0f4a34951055b43afab304b5c60919c9
TWILIO_PHONE_NUMBER=+14632175613
```

### Frontend `.env.local`
```
LIVEKIT_URL=wss://test-voice-bot-fd6qy6cu.livekit.cloud
LIVEKIT_API_KEY=APIVYTe7eb9UmEv
LIVEKIT_API_SECRET=bWhejV80AWmltf0C8kQ1FVral4g4QfI0A71JTCaUFs6A
TWILIO_ACCOUNT_SID=ACd2fe6190353086ca693c87c0568dc90f
TWILIO_AUTH_TOKEN=0f4a34951055b43afab304b5c60919c9
TWILIO_PHONE_NUMBER=+14632175613
TWILIO_TWIML_URL=http://twimlets.com/echo?Twiml=...
```

---

## 🐛 Troubleshooting

### Backend won't start

**Error:** `ModuleNotFoundError: No module named 'livekit'`

**Fix:**
```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/BackEnd/agent-starter-python
uv sync
```

Or if not using uv:
```bash
python3 -m pip install -e .
```

### Frontend won't start

**Error:** `Cannot find module 'next'`

**Fix:**
```bash
cd /var/www/html/vikas/2025-Nov-21-Voicebot/FrontEnd/agent-starter-react/agent-starter-react
npm install
```

### Phone call doesn't connect

**Check:**
1. Backend is running: `uv run python -m src.agent dev`
2. Telephony is configured: `uv run python setup_telephony.py`
3. Check backend logs for "Job received" message

### No audio on call

**Check:**
1. `ELEVENLABS_API_KEY` is set in backend `.env.local`
2. Backend logs show "STT: ElevenLabs" and "TTS: ElevenLabs"
3. Try calling again (first call may be slower)

---

## 📁 Project Structure

```
/var/www/html/vikas/2025-Nov-21-Voicebot/
├── BackEnd/agent-starter-python/
│   ├── src/
│   │   ├── agent.py              # Main agent code
│   │   ├── conversation_logger.py
│   │   └── elevenlabs_server.py
│   ├── .env.local                # Backend config
│   ├── setup_telephony.py        # One-time telephony setup
│   ├── setup_sip_trunk.py        # SIP trunk management
│   └── setup_dispatch_rule.py    # Dispatch rule management
│
├── FrontEnd/agent-starter-react/agent-starter-react/
│   ├── app/
│   │   ├── page.tsx              # Main UI
│   │   └── api/
│   │       └── twilio/
│   │           └── outbound-call/route.ts  # Outbound call API
│   ├── .env.local                # Frontend config
│   └── package.json
│
├── START_HERE.md                 # This file
└── TELEPHONY_SETUP.md            # Detailed telephony docs
```

---

## 🎉 You're All Set!

Your voice AI is ready to:
- ✅ Answer phone calls via Twilio
- ✅ Talk to users in the browser
- ✅ Make outbound calls
- ✅ Handle multiple conversations simultaneously

**Next:** Run the 3 steps above and start testing!