# Make.com Integration Guide: 12-Month EOT Campaign

## 🎯 Overview
This guide explains exactly how Lia selects the **12-month templates** and how Make.com should call the API.

---

## 📍 Step 1: How Lia Identifies "12 Months to Go"

### Lookup Logic (from `app/lia_outbound.py` lines 38-48):

```python
def select_outbound_stage(payments_remaining):
    if payments_remaining >= 16:
        return "18"  # 18-month stage
    elif payments_remaining >= 10:
        return "12"  # 👈 12-MONTH STAGE
    elif payments_remaining >= 7:
        return "9"   # 9-month stage
    elif payments_remaining >= 4:
        return "6"   # 6-month stage
    else:
        return "3"   # 3-month stage
```

### ✅ 12-Month Trigger:
**If `payments_remaining` is between 10 and 15** → System selects **stage "12"**

Examples:
- `payments_remaining: 15` → Stage "12" ✅
- `payments_remaining: 12` → Stage "12" ✅
- `payments_remaining: 10` → Stage "12" ✅
- `payments_remaining: 9` → Stage "9" ❌ (Wrong stage)
- `payments_remaining: 16` → Stage "18" ❌ (Wrong stage)

---

## 📝 Step 2: The Exact 12-Month Templates

### Template A: 12-Month NEW Car (EOT_12_NEW)
**Template Key**: `EOT_12_NEW`  
**Use When**: Customer has a **NEW** Audi on PCP/HP

```
Hi [customer_name], it's Lia from Lincoln Audi.

I've just been reviewing your account and you're about 12 months from the end of your agreement.
This is usually when customers start looking at their next steps — mainly because the car is still strong in the market, you're approaching MOT and warranty timelines, and Audi often provides early loyalty support around this point.

If you'd like, I can put together a quick overview of your options.
Is there a particular model you've been thinking about next?
```

**Character Count**: 535 characters

---

### Template B: 12-Month USED Car (EOT_12_USED)
**Template Key**: `EOT_12_USED`  
**Use When**: Customer has an **APPROVED USED** Audi on PCP/HP

```
Hi [customer_name], it's Lia from Lincoln Audi.

I've just been reviewing your account and you're roughly 12 months from the end of your agreement.

If there's a type of car you'd like to move into next, this is a great time to start looking — and depending on your profile, you may also qualify for loyalty contributions that can make moving into a new Audi more affordable than you'd expect.

What kind of car are you thinking about for your next one?
```

**Character Count**: 442 characters

---

## 🔧 Step 3: Template Selection Logic (from `app/lia_outbound.py` lines 51-65)

```python
def select_outbound_template(stage, asset_type):
    # For 12-month stage with NEW car:
    # stage = "12", asset_type = "new"
    # → template_key = "EOT_12_NEW"
    
    # For 12-month stage with USED car:
    # stage = "12", asset_type = "used"
    # → template_key = "EOT_12_USED"
    
    asset_suffix = "NEW" if asset_type.lower() == "new" else "USED"
    template_key = f"EOT_{stage}_{asset_suffix}"
    
    return LIA_EOT_CAMPAIGN_OPENERS.get(template_key)
```

### Template Selection Table:

| Stage | asset_type | Template Key | Template Used |
|-------|------------|--------------|---------------|
| "12" | "new" | `EOT_12_NEW` | 12-Month NEW template (535 chars) |
| "12" | "used" | `EOT_12_USED` | 12-Month USED template (442 chars) |

---

## 🚀 Step 4: Make.com API Call - EXACT FORMAT

### API Endpoint:
```
POST https://your-replit-url.repl.co/api/lia/outbound
```

### Headers:
```
x-api-key: your-api-key-here
Content-Type: application/json
```

---

### Example 1: 12-Month NEW Car Customer

**Scenario**: Customer "John Smith" has 12 payments remaining on a NEW Audi A3

```json
{
  "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payments_remaining": 12,
  "campaign": "pcp_stage_auto",
  "asset_type": "new",
  "channel": "whatsapp",
  "sandbox_mode": false
}
```

**API Response**:
```json
{
  "message_text": "Hi John Smith, it's Lia from Lincoln Audi.\n\nI've just been reviewing your account and you're about 12 months from the end of your agreement.\nThis is usually when customers start looking at their next steps — mainly because the car is still strong in the market, you're approaching MOT and warranty timelines, and Audi often provides early loyalty support around this point.\n\nIf you'd like, I can put together a quick overview of your options.\nIs there a particular model you've been thinking about next?",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": "+447700900123",
  "stage": "12"
}
```

---

### Example 2: 12-Month USED Car Customer

**Scenario**: Customer "Sarah Jones" has 13 payments remaining on an APPROVED USED Audi Q3

```json
{
  "customer_id": "b2c3d4e5-f6a7-8901-bcde-fg2345678901",
  "payments_remaining": 13,
  "campaign": "pcp_stage_auto",
  "asset_type": "used",
  "channel": "whatsapp",
  "sandbox_mode": false
}
```

**API Response**:
```json
{
  "message_text": "Hi Sarah Jones, it's Lia from Lincoln Audi.\n\nI've just been reviewing your account and you're roughly 12 months from the end of your agreement.\n\nIf there's a type of car you'd like to move into next, this is a great time to start looking — and depending on your profile, you may also qualify for loyalty contributions that can make moving into a new Audi more affordable than you'd expect.\n\nWhat kind of car are you thinking about for your next one?",
  "conversation_id": "b2c3d4e5-f6a7-8901-bcde-fg2345678901",
  "to_number": "+447700900456",
  "stage": "12"
}
```

---

### Example 3: Test Mode (Sandbox)

**Scenario**: Testing without sending to real phone numbers

```json
{
  "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "payments_remaining": 12,
  "campaign": "pcp_stage_auto",
  "asset_type": "new",
  "channel": "whatsapp",
  "sandbox_mode": true
}
```

**API Response**:
```json
{
  "message_text": "Hi John Smith, it's Lia from Lincoln Audi...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": null,
  "stage": "12"
}
```

**Note**: `to_number` is `null` in sandbox mode (for Twilio testing)

---

## 📊 Step 5: Make.com Workflow

### Recommended Flow:

1. **Trigger**: Monthly VWFS CSV upload or scheduled cron
2. **Filter**: Only process customers with `payments_remaining` between 10 and 15
3. **HTTP Request**: Call `/api/lia/outbound` with:
   - `customer_id` (from your database)
   - `payments_remaining` (from VWFS data)
   - `campaign: "pcp_stage_auto"` (auto-selects stage)
   - `asset_type` (from your database: "new" or "used")
   - `sandbox_mode: false` (production)
4. **Twilio**: Send WhatsApp message using:
   - **To**: Use `to_number` from API response
   - **Body**: Use `message_text` from API response
5. **Log**: Store `conversation_id` and `stage` for tracking

---

## 🔍 Step 6: How to Know NEW vs USED?

You need to determine `asset_type` from your database. Common ways:

### Option A: Check original price (most reliable)
```sql
SELECT 
  CASE 
    WHEN original_price > 25000 THEN 'new'
    ELSE 'used'
  END as asset_type
FROM agreement
```

### Option B: Check vehicle age at purchase
```sql
SELECT 
  CASE 
    WHEN vehicle_age_at_purchase <= 1 THEN 'new'
    ELSE 'used'
  END as asset_type
FROM agreement
```

### Option C: Manual flag in database
If you have a column `product_type` or `vehicle_condition`:
```sql
SELECT product_type as asset_type FROM agreement
```

---

## ✅ Quick Checklist for Make.com Developer

- [ ] API endpoint URL configured: `POST /api/lia/outbound`
- [ ] Header `x-api-key` set correctly
- [ ] Request body includes:
  - [ ] `customer_id` or `reg`
  - [ ] `payments_remaining` (must be 10-15 for 12-month stage)
  - [ ] `campaign: "pcp_stage_auto"`
  - [ ] `asset_type: "new"` or `"used"`
  - [ ] `sandbox_mode: false` (production) or `true` (testing)
- [ ] Make.com reads response fields:
  - [ ] `message_text` → Send to Twilio body
  - [ ] `to_number` → Send to Twilio recipient
  - [ ] `conversation_id` → Log for tracking
  - [ ] `stage` → Log for analytics

---

## 🐛 Troubleshooting

### Issue: Wrong template selected
**Check**: Is `payments_remaining` between 10-15?
**Check**: Is `asset_type` exactly `"new"` or `"used"` (lowercase)?

### Issue: `to_number` is null
**Check**: Is `sandbox_mode: false`?
**Check**: Does customer have a phone number in database?

### Issue: Customer name shows "Hi there" instead of real name
**Check**: Does `customer_id` exist in database?
**Check**: Does customer have `first_name` and `last_name` populated?

---

## 📞 Contact
If you need help testing the endpoint, use the FastAPI docs:
`http://localhost:8000/docs` → `POST /api/lia/outbound` → "Try it out"