# POST /api/lia/outbound - Test Examples

This endpoint generates outbound WhatsApp message content for renewal customers.

## Endpoint Details
- **URL**: `POST /api/lia/outbound`
- **Authentication**: Requires `x-api-key` header
- **Response Model**: `OutboundResponse`

## Example 1: Auto-select stage from payments_remaining (12-month stage, NEW car)

```json
POST /api/lia/outbound
Headers:
  x-api-key: your-api-key-here
  Content-Type: application/json

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

**Expected 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...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": "+447700900123",
  "stage": "12"
}
```

## Example 2: 9-month stage with USED car

```json
{
  "reg": "AB12XYZ",
  "payments_remaining": 8,
  "campaign": "pcp_stage_auto",
  "asset_type": "used",
  "channel": "whatsapp",
  "sandbox_mode": false
}
```

**Expected Response**:
```json
{
  "message_text": "Hi Sarah Jones, it's Lia from Lincoln Audi.\n\nYou're now around 9 months away from the end of your Approved Used agreement...",
  "conversation_id": "customer-uuid-here",
  "to_number": "+447700900456",
  "stage": "9"
}
```

## Example 3: Sandbox mode (testing without real phone numbers)

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

**Expected Response**:
```json
{
  "message_text": "Hi John Smith, it's Lia from Lincoln Audi.\n\nI've just been reviewing your account and you're around 6 months away from the end of your agreement...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": null,
  "stage": "6"
}
```

**Note**: `to_number` is `null` in sandbox mode because Twilio sandbox only works with pre-approved numbers.

## Example 4: 3-month stage (end-of-contract urgency)

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

**Expected Response**:
```json
{
  "message_text": "Hi John Smith, it's Lia from Lincoln Audi.\n\nYou're now around 3 months from the end of your agreement, so this is the point where we normally invite customers in for their end-of-contract check...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": "+447700900123",
  "stage": "3"
}
```

## Example 5: 18-month stage (early planning)

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

**Expected Response**:
```json
{
  "message_text": "Hi John Smith, it's Lia from Lincoln Audi.\n\nI've been reviewing your account and noticed you're around 18 months away from the end of your agreement...",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": "+447700900123",
  "stage": "18"
}
```

## Stage Selection Logic

The endpoint automatically maps `payments_remaining` to campaign stages:

| Payments Remaining | Stage Selected | Template Used |
|-------------------|----------------|---------------|
| 16+ months | "18" | EOT_18_NEW / EOT_18_USED |
| 10-15 months | "12" | EOT_12_NEW / EOT_12_USED |
| 7-9 months | "9" | EOT_9_NEW / EOT_9_USED |
| 4-6 months | "6" | EOT_6_NEW / EOT_6_USED |
| 1-3 months | "3" | EOT_3_NEW / EOT_3_USED |

## Make.com Integration Flow

1. **Make.com webhook** receives monthly VWFS data upload
2. **Make.com** calls `/api/lia/outbound` with:
   - `customer_id` or `reg` (vehicle registration)
   - `payments_remaining` (from VWFS data)
   - `campaign: "pcp_stage_auto"` (auto-select stage)
   - `asset_type: "new"` or `"used"`
   - `sandbox_mode: false` (production)
3. **Endpoint returns** personalized message_text
4. **Make.com** sends message via Twilio using `to_number` and `message_text`

## Error Handling

### Missing payments_remaining
```json
Response:
{
  "message_text": "Error: Unable to determine campaign stage from payments_remaining",
  "conversation_id": null,
  "to_number": null,
  "stage": null
}
```

### Invalid template
```json
Response:
{
  "message_text": "Error: No template found for stage 12 and asset_type invalid",
  "conversation_id": null,
  "to_number": null,
  "stage": "12"
}
```

## Testing in FastAPI Docs

1. Navigate to: `http://localhost:8000/docs`
2. Find: `POST /api/lia/outbound`
3. Click "Try it out"
4. Add header: `x-api-key: your-api-key-here`
5. Paste example JSON body
6. Click "Execute"
7. View response below

## Notes

- The endpoint does **NOT** send the WhatsApp message - it only prepares the content
- Make.com handles the actual message sending via Twilio
- `conversation_id` is generated from `customer_id` or a new UUID if customer not found
- `[customer_name]` placeholder is automatically replaced with actual customer name from database
- If customer not found, defaults to "there" (e.g., "Hi there, it's Lia from Lincoln Audi...")