# RateRight Phone AI 📞

AI receptionist for RateRight. Answers unanswered calls, qualifies leads, logs to Growth Engine CRM.

## Status

✅ **Phase 1**: Vapi assistants created with Australian voice
🔄 **Phase 2**: Twilio forwarding (needs Vapi phone numbers)
✅ **Phase 3**: Growth Engine integration ready
✅ **Phase 4**: Notifications ready (needs Slack webhook + Michael's number)

## Quick Start

### 1. Setup Vapi Assistants (DONE ✅)

Already created:
- **Main Line Assistant**: `6485d7c9-ae5b-44cb-a4a9-3f9536753c5b`
- **Line 2 Assistant**: `9fcbe4cf-c435-4911-a755-b8e9e06bf216`

Voice: Australian female (Azure `en-AU-NatashaNeural`)

### 2. Get Vapi Phone Numbers

1. Login to https://dashboard.vapi.ai
2. Go to "Phone Numbers"
3. Import or buy two Australian phone numbers
4. Assign each to an assistant:
   - Number 1 → Main Line Assistant (`6485d7c9-ae5b-44cb-a4a9-3f9536753c5b`)
   - Number 2 → Line 2 Assistant (`9fcbe4cf-c435-4911-a755-b8e9e06bf216`)

### 3. Configure Environment

Copy `.env.example` to `.env` and fill in:

```bash
# Vapi (already have these)
VAPI_API_KEY=your_vapi_key_here
VAPI_PUBLIC_KEY=904af378-1d7a-40b2-aa02-cfbafb39fe9a

# Growth Engine
GROWTH_ENGINE_API_URL=https://api.growthengine.com
GROWTH_ENGINE_API_KEY=your_key_here

# Notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
MICHAEL_PHONE=+61412345678

# Server
PORT=3000
WEBHOOK_BASE_URL=https://your-domain.com  # Your public URL
```

### 4. Configure Twilio Forwarding

```bash
npm run setup:twilio
```

This sets up:
- +61 468 087 171 → Forward to Vapi after 2 rings (~8 seconds)

### 5. Start the Server

```bash
npm start
```

The webhook server will run on port 3000 and receive call events from Vapi.

### 6. Deploy

Deploy to a public server (or use ngrok for testing):

```bash
# Option A: Using ngrok for testing
ngrok http 3000

# Option B: Deploy to production
# (Railway, Render, Heroku, etc.)
```

Update `WEBHOOK_BASE_URL` in `.env` with your public URL.

### 7. Configure Vapi Webhooks

1. Go to https://dashboard.vapi.ai
2. Go to each assistant's settings
3. Set "Server URL" to: `https://your-domain.com/vapi/webhook`
4. Enable these events:
   - `call.started`
   - `call.ended`
   - `transcript` (optional)

## How It Works

```
Phone rings → 5 rings (25s) → No answer?
  ↓
Forward to Vapi AI
  ↓
AI Assistant (Sarah) answers
  ↓
Qualifies lead (worker or hirer)
  ↓
Call ends → Webhook to our server
  ↓
Extract lead data from transcript
  ↓
┌─────────────┬────────────────┐
│ Growth      │ Notifications  │
│ Engine CRM  │ (Slack + SMS)  │
└─────────────┴────────────────┘
```

## The AI Script

Sarah (the AI) follows this flow:

1. **Greeting**: "G'day, thanks for calling RateRight. This is Sarah - how can I help you today?"

2. **Qualify**: "Are you looking to find work, or looking to hire workers?"

3. **If Worker**:
   - What trade?
   - Where based?
   - Collect name and number

4. **If Hirer**:
   - What kind of workers?
   - How many needed?
   - When do they start?
   - Where's the job?
   - Collect name and number

## API Endpoints

- `GET /` - Health check
- `POST /vapi/webhook` - Vapi event webhook

## File Structure

```
rateright-phone-ai/
├── src/
│   ├── index.js                  # Main server
│   ├── vapi/
│   │   ├── setup.js              # Assistant creation
│   │   └── webhook.js            # Webhook handler
│   ├── twilio/
│   │   └── forwarding.js         # Call routing config
│   ├── growth-engine/
│   │   └── client.js             # CRM integration
│   └── notifications/
│       └── alert.js              # Slack + SMS
├── scripts/
│   ├── setup-vapi.js             # One-time Vapi setup
│   └── setup-twilio.js           # One-time Twilio setup
└── package.json
```

## Testing

1. Call +61 468 087 171
2. Don't answer on the other end
3. After 5 rings, AI should pick up
4. Have a conversation
5. Check:
   - Lead appears in Growth Engine
   - Slack notification sent
   - SMS sent to Michael

## Troubleshooting

**AI doesn't pick up:**
- Check Twilio forwarding is configured
- Check Vapi phone numbers are assigned to assistants
- Check webhook URL is public and accessible

**No notifications:**
- Check `SLACK_WEBHOOK_URL` is set
- Check `MICHAEL_PHONE` is set
- Check Twilio credentials for SMS

**Leads not logged:**
- Check `GROWTH_ENGINE_API_KEY` is set
- Check Growth Engine API endpoint is correct
- Check server logs for errors

## Next Steps

- [ ] Get Vapi phone numbers
- [ ] Configure Twilio forwarding
- [ ] Set up Growth Engine API key
- [ ] Set up Slack webhook
- [ ] Add Michael's phone number
- [ ] Deploy to production
- [ ] Test both phone lines
- [ ] Update Line 2 script when Michael specifies use case

## Cost Estimate

- **Vapi**: ~$0.10-0.15 per minute of conversation
- **Twilio**: Standard call forwarding rates
- **Deepgram**: Included in Vapi
- **Azure TTS**: Included in Vapi

Estimated: **$0.15-0.25 per call** (assuming 2-3 min average)

## Support

Questions? Check the code or BUILD.md for details.

Built with ❤️ for RateRight