# BUILD.md - Detailed Build Spec

## Overview
AI phone receptionist for RateRight. Answers calls when humans don't, qualifies leads, logs to CRM.

---

## Phase 1: Vapi Assistant Setup

### Create Two Assistants via Vapi API

**Assistant 1: RateRight Main**
- Name: `rateright-main`
- Voice: Australian female, warm, friendly (check Vapi voice library)
- First message: "G'day, thanks for calling RateRight. This is Sarah - how can I help you today?"

**Qualification Script:**
```
1. Greet warmly
2. Ask: "Are you looking to find work, or looking to hire workers?"

IF LOOKING FOR WORK:
- "Great! What trade are you in?"
- "And whereabouts are you based?"
- "Perfect. I'll get one of the team to give you a call back shortly to chat about opportunities. Can I confirm your name and best number?"
- "Thanks [name], speak soon!"

IF LOOKING TO HIRE:
- "No worries! What kind of workers are you after?"
- "How many do you need, roughly?"
- "When do you need them to start?"
- "And where's the job located?"
- "I'll get one of our team to call you back within the hour with some options. Can I grab your name and best contact?"
- "Thanks [name], we'll be in touch shortly!"

IF UNCLEAR:
- "No worries, I can help with that. Is it about finding work or hiring workers?"
```

**Assistant 2: Second Line** (placeholder til Michael specifies)
- Name: `rateright-line2`
- Script: TBD - start with same as main

---

## Phase 2: Twilio Call Forwarding

### Configure No-Answer Forwarding

For each number, set up:
1. Call comes in
2. Ring for 25 seconds (~5 rings)
3. If no answer → forward to Vapi webhook

**Twilio Setup:**
```javascript
// Use TwiML or Twilio API to set up call forwarding
// On no-answer (25s timeout) → POST to Vapi's inbound call webhook
```

Numbers:
- +61 468 087 171 → rateright-main assistant
- +61 426 246 472 → rateright-line2 assistant

---

## Phase 3: Growth Engine Integration

### Log Leads to CRM

When call ends, Vapi sends webhook with transcript + extracted data.

**Capture:**
- Caller phone number
- Caller name (if given)
- Type: worker or hirer
- Trade/workers needed
- Location
- Timeline
- Full transcript

**POST to Growth Engine:**
```
POST /api/leads
{
  source: "phone-ai",
  phone: "+61...",
  name: "John",
  type: "hirer",
  trade_needed: "carpenters",
  quantity: "3-4",
  location: "Parramatta",
  timeline: "next week",
  transcript: "...",
  created_at: "..."
}
```

Check Growth Engine's existing API for exact endpoint/format.

---

## Phase 4: Notifications

### Instant Alert to Michael

When a call is handled:
1. Slack message to #growth-alerts
2. Text to Michael's phone (use Twilio)

Format:
```
📞 AI Call Handled
Type: Hirer looking for workers
Name: John Smith
Trade: 3-4 carpenters
Location: Parramatta NSW
Timeline: Next week
Phone: 0412 345 678
```

---

## File Structure

```
rateright-phone-ai/
├── CLAUDE.md
├── BUILD.md
├── package.json
├── .env.example
├── src/
│   ├── index.js          # Main entry
│   ├── vapi/
│   │   ├── setup.js      # Create/update assistants
│   │   └── webhook.js    # Handle call events
│   ├── twilio/
│   │   └── forwarding.js # Configure call routing
│   ├── growth-engine/
│   │   └── client.js     # Log leads to CRM
│   └── notifications/
│       └── alert.js      # Slack + SMS alerts
└── scripts/
    ├── setup-vapi.js     # One-time assistant creation
    └── setup-twilio.js   # One-time forwarding config
```

---

## Testing Checklist

- [ ] Can create Vapi assistant via API
- [ ] Voice sounds natural (Aussie, friendly)
- [ ] Twilio forwards after 5 rings (25s)
- [ ] AI handles "looking for work" path
- [ ] AI handles "looking to hire" path
- [ ] Transcript captured correctly
- [ ] Lead logged to Growth Engine
- [ ] Slack notification sent
- [ ] SMS notification sent

---

## API Keys

Load from environment:
```bash
source ~/.env.rateright-phone
# Contains: VAPI_API_KEY, VAPI_PUBLIC_KEY

# Twilio already in environment:
# TWILIO_ACCOUNT_SID, TWILIO_API_KEY_SID, TWILIO_API_KEY_SECRET, TWILIO_PHONE_NUMBER
```

---

## Done Criteria

1. Call +61 468 087 171, don't answer on other end
2. AI picks up after 5 rings
3. Have a conversation, get qualified
4. Lead appears in Growth Engine
5. Slack + SMS notification received

Same for second number.

---

## Notes

- Keep it simple - MVP first
- Don't over-engineer
- Test with real calls as you go
- Ask Rivet (Clawdbot) if you need Growth Engine API details