# Settings API

Manage your agent configuration, email preferences, and follow-up message templates.

## Get Settings

```
GET /api/v1/settings
```

Returns your complete agent settings including agent preferences, email preferences, and follow-up templates.

**Response:**

```json
{
  "data": {
    "agentName": "Jane",
    "customInstructions": null,
    "timezone": "America/New_York",
    "workingHours": {
      "start": "09:00",
      "end": "17:00",
      "days": [1, 2, 3, 4, 5]
    },
    "defaultShowingDuration": 30,
    "emailSignOff": null,
    "publicChatIntro": null,
    "prescreeningEnabled": true,
    "profilePublic": true,
    "licenseNumber": null,
    "publicPhone": null,
    "followupEnabled": false,
    "followupIdleHours": 48,
    "followupMaxSteps": 3,
    "voiceEnabled": true,
    "voicePromptAddition": null,
    "voiceFirstMessage": null,
    "allowInternationalPhone": false,
    "bookingUrl": null,
    "externalLinkUrl": null,
    "externalLinkLabel": null,
    "showExternalLinkOnProfile": false,
    "showExternalLinkOnCompletion": false,
    "callHumanEnabled": false,
    "followupTemplates": [],
    "showingCalendarId": null,
    "showingBufferMinutes": 15,
    "maxShowingsPerDay": 10,
    "emailPreferences": {
      "marketing": false,
      "applicationNotifications": true,
      "notifyProspectOnReview": false,
      "emailProspectMatches": false,
      "schedulingEmailEnabled": false,
      "newInquiryNotifications": true,
      "showingBookedNotifications": true,
      "followupDueNotifications": false
    }
  }
}
```

## Update Settings

```
PATCH /api/v1/settings
```

Update one or more settings. Only include the fields you want to change — unmentioned fields are preserved.

**Request Body (all fields optional):**

| Field | Type | Description |
|-------|------|-------------|
| `agentName` | string | Display name for your AI agent |
| `customInstructions` | string | Custom system prompt instructions |
| `timezone` | string | IANA timezone (e.g. `America/New_York`) |
| `workingHours` | object | `{ start, end, days }` — HH:MM times, days array (0=Sun) |
| `defaultShowingDuration` | number | Showing length in minutes: `30`, `45`, or `60` |
| `emailSignOff` | string | Email signature sign-off text |
| `publicChatIntro` | string | Welcome message for public chat |
| `prescreeningEnabled` | boolean | Enable/disable public prescreening |
| `profilePublic` | boolean | Make agent profile publicly visible |
| `licenseNumber` | string | Real estate license number |
| `publicPhone` | string | Phone number shown on public pages |
| `followupEnabled` | boolean | Enable automatic follow-ups |
| `followupIdleHours` | number | Hours of inactivity before follow-up: `24`, `48`, or `72` |
| `followupMaxSteps` | number | Max follow-up sequence steps: `1`, `2`, or `3` |
| `voiceEnabled` | boolean | Enable voice agent on public pages |
| `voicePromptAddition` | string | Additional voice agent instructions |
| `voiceFirstMessage` | string | Custom voice greeting |
| `allowInternationalPhone` | boolean | Accept international phone numbers |
| `bookingUrl` | string | External booking URL (must be valid URL, or `""` to clear) |
| `externalLinkUrl` | string | External link URL on profile/completion |
| `externalLinkLabel` | string | Label for external link |
| `showExternalLinkOnProfile` | boolean | Show external link on profile page |
| `showExternalLinkOnCompletion` | boolean | Show external link on completion page |
| `callHumanEnabled` | boolean | Enable "Call Human" button |
| `followupTemplates` | array | Per-step message templates (see below) |
| `showingCalendarId` | string | Google Calendar ID for showings (default: primary) |
| `showingBufferMinutes` | number | Buffer between showings: `15`, `30`, or `60` |
| `maxShowingsPerDay` | number | Max showings per day: `1`–`20` |
| `emailPreferences` | object | Email notification preferences (see below) |

**Follow-up Templates:**

```json
{
  "followupTemplates": [
    { "step": 1, "template": "Hey {contactName}, this is {agentName}. Just checking in about {propertyAddress}!" },
    { "step": 2, "template": "Hi {contactName}, wanted to follow up one more time..." }
  ]
}
```

Templates support `{contactName}`, `{agentName}`, and `{propertyAddress}` placeholders. When a template matches the follow-up step, it's used directly instead of generating a message with AI.

**Email Preferences:**

```json
{
  "emailPreferences": {
    "marketing": true,
    "applicationNotifications": true,
    "notifyProspectOnReview": false,
    "emailProspectMatches": false,
    "schedulingEmailEnabled": true,
    "newInquiryNotifications": true,
    "showingBookedNotifications": true,
    "followupDueNotifications": false
  }
}
```

**Response:** Returns the full updated settings object (same shape as GET).

## Follow-up Settings

A dedicated sub-resource for follow-up automation settings.

```
GET /api/v1/settings/followups
PATCH /api/v1/settings/followups
```

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | boolean | Enable/disable automatic follow-ups |
| `idleHours` | number | Hours before follow-up triggers: `24`, `48`, or `72` |
| `maxSteps` | number | Max follow-up steps (1–3) |

**Response (`200 OK`):**

```json
{
  "data": {
    "enabled": true,
    "idleHours": 48,
    "maxSteps": 3
  }
}
```