# 19 — SMS / Twilio Integration

## Context
Fogbreak replaces Follow Up Boss (which has built-in texting) and adds SMS capabilities across all modules. Two-way SMS for agent-client communication, SMS drip campaigns, showing confirmations via text, and AI-powered auto-responses.

## What to Build

### 1. Twilio Integration
Create `app/api/sms.php`:
- Twilio API for sending/receiving SMS
- Phone number provisioning per agent or per brokerage
- Webhook endpoint for inbound messages
- Message delivery status tracking

### 2. Two-Way SMS Inbox
- Threaded conversations per client (like iMessage view)
- Agents see all their SMS conversations in one place
- Shared team inbox option (multiple agents see same thread)
- Unread count badges
- Search messages

### 3. SMS in Drip Campaigns
Extend `drips.php`:
- Drip steps can be email OR SMS
- SMS content shorter (160 chars or smart multi-part)
- AI generates SMS-appropriate content
- Opt-out handling (STOP → auto-unsubscribe)
- Delivery time optimization (don't text at 2 AM)

### 4. Showing Confirmations via SMS
Integration with showings (instruction 05):
- "You have a showing request for 123 Ocean Ave at 2pm tomorrow. Reply Y to confirm, N to decline."
- Auto-process Y/N replies
- Reminder texts 1 hour before showing

### 5. AI Auto-Response
When agent is unavailable:
- AI responds to common questions via SMS
- "What's the price?" → AI pulls listing data and responds
- "Is this still available?" → AI checks status and responds
- "Can I see it Saturday?" → AI checks availability and suggests times
- Handoff to agent for complex questions

### 6. Compliance
- TCPA compliance (consent tracking)
- Opt-in/opt-out management
- Quiet hours (no texts before 8am or after 9pm local time)
- Message logging for compliance records
- Do-not-call list integration

## Endpoints
```
POST /api/sms.php?action=send              # Send SMS
GET  /api/sms.php?action=conversations     # List conversations
GET  /api/sms.php?action=thread&client=X   # Get conversation thread
POST /api/sms.php?action=webhook           # Twilio inbound webhook
GET  /api/sms.php?action=status&msg=X      # Delivery status
POST /api/sms.php?action=provision_number  # Get new phone number
```

## Acceptance Criteria
- [ ] Twilio integration for send/receive SMS
- [ ] Two-way threaded SMS inbox
- [ ] SMS steps in drip campaigns
- [ ] Showing confirmation via text (Y/N reply)
- [ ] AI auto-response for common questions
- [ ] TCPA compliance with opt-in/opt-out
- [ ] Quiet hours enforcement
- [ ] All features tenant-aware