> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Full SDK configuration reference

# Configuration

All SDK options and their defaults.

## Required Fields

Every SDK initialization requires these fields:

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',   // Moss backend URL
  applicationId: 'YOUR_APP_ID',               // From the Dashboard
  userId: 'user-123',                          // Your user's identifier
  getJwt: () => fetchMossToken(),              // JWT token provider
}}>
```

| Field           | Type                    | Description                             |
| --------------- | ----------------------- | --------------------------------------- |
| `apiUrl`        | `string`                | Moss backend API URL                    |
| `applicationId` | `string`                | Application UUID from the Dashboard     |
| `userId`        | `string`                | Unique identifier for the current user  |
| `getJwt`        | `() => Promise<string>` | Function that returns a fresh JWT token |

<Info>
  You can provide `applicationName` instead of `applicationId` if preferred. At least one is required.
</Info>

## Common Options

Options you'll likely want to configure.

| Option           | Type                       | Default      | Description                 |
| ---------------- | -------------------------- | ------------ | --------------------------- |
| `language`       | `'en' \| 'ko'`             | Auto-detect  | UI language                 |
| `debugMode`      | `boolean`                  | `false`      | Enable debug logging and UI |
| `screenshotMode` | `'fullpage' \| 'viewport'` | `'fullpage'` | Screenshot capture mode     |

```tsx theme={null}
<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: 'user-123',
  getJwt: () => fetchMossToken(),
  language: 'en',
  debugMode: false,
  screenshotMode: 'fullpage',
}}>
```

## All Options

### Authentication

| Option   | Type                    | Default | Description                               |
| -------- | ----------------------- | ------- | ----------------------------------------- |
| `getJwt` | `() => Promise<string>` | —       | Function to fetch fresh JWT (recommended) |
| `jwt`    | `string`                | —       | Static JWT token (no auto-refresh)        |

### Display

| Option           | Type                       | Default      | Description                                                                                   |
| ---------------- | -------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
| `language`       | `'en' \| 'ko'`             | Auto-detect  | UI language                                                                                   |
| `screenshotMode` | `'fullpage' \| 'viewport'` | `'fullpage'` | How screenshots are captured                                                                  |
| `appearance`     | `AppearanceInput`          | `'blue'`     | Visual theme (preset name or custom object)                                                   |
| `displayMode`    | `'chat' \| 'headless'`     | `'chat'`     | Guide display: full chat modal, or a positioned tooltip bubble near highlighted elements      |
| `headless`       | `HeadlessConfig`           | —            | Options that apply in headless mode: spotlight dim overlay, animated cursor, completion toast |

### Behavior

| Option                         | Type                      | Default         | Description                            |
| ------------------------------ | ------------------------- | --------------- | -------------------------------------- |
| `useVision`                    | `boolean`                 | Backend setting | Override vision (screenshot analysis)  |
| `observeTargetSelector`        | `string`                  | `'body'`        | CSS selector for DOM observation scope |
| `pageSanitizationScript`       | `(doc: Document) => void` | —               | Clean the DOM before context capture   |
| `enableSessionRecording`       | `boolean`                 | `true`          | Upload session recordings to dashboard |
| `enableScreenHistoryRecording` | `boolean`                 | `false`         | Include screen history in AI context   |

### Privacy & Redaction

| Option               | Type                                                      | Default | Description                                                                           |
| -------------------- | --------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `redactAllInputs`    | `boolean`                                                 | `true`  | Redact values of all input-type elements; opt out per field with `data-moss-unredact` |
| `redactionSelectors` | `string[]`                                                | —       | Additional CSS selectors redacted identically to `data-moss-redact`                   |
| `userMetadata`       | `Record<string, string \| number \| boolean \| string[]>` | —       | User attributes (role, tier) for personalized guidance; avoid raw PII                 |

See [Advanced > Redacting Sensitive Content](/en/sdk/advanced#redacting-sensitive-content).

### Integrations

| Option            | Type                                         | Default | Description                                                                                                    |
| ----------------- | -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `onSupportTicket` | `(handoff) => Promise<SupportTicketOutcome>` | —       | Host callback for brokered support-ticket filing; see [Support Ticket Handoff](/en/sdk/support-ticket-handoff) |

### Session Management

```tsx theme={null}
sessionConfig: {
  inactivityTimeout: 30,    // Minutes before new session (default: 30)
  maxSessionAge: 2,         // Hours before forcing new session (default: 2)
  showNotification: true,   // Notify when auto-starting session (default: true)
}
```

### Debug

| Option      | Type       | Default         | Description                                                   |
| ----------- | ---------- | --------------- | ------------------------------------------------------------- |
| `logLevel`  | `LogLevel` | `LogLevel.INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARN`, `ERROR`, `SILENT` |
| `debugMode` | `boolean`  | `false`         | Enable debug UI and verbose logging                           |

### Stability

The SDK waits for the page to stabilize before capturing context. This is configured via the `stability` field. See [Advanced > Stability Tuning](/en/sdk/advanced#stability-tuning) for details.

```tsx theme={null}
stability: {
  layers: {
    networkIdle: true,        // Wait for network requests (default: true)
    domMutations: true,       // Wait for DOM to stop changing (default: true)
    loadingIndicators: false, // Wait for spinners/skeletons (default: false)
    frameReadiness: true,     // Wait for same-origin frames to finish loading (default: true)
    resourceQuiet: true,      // Wait for resource loads to go quiet (default: true)
    layoutShift: false,       // Wait for layout shifts (default: false)
    browserIdle: true,        // Wait for browser idle (default: true)
    finalFrame: true,         // Wait for animation frame (default: true)
  },
}
```

***

## Full TypeScript Interface

```typescript theme={null}
interface MossSDKConfig {
  // Required
  apiUrl: string;
  userId: string;
  applicationId?: string;     // At least one of applicationId
  applicationName?: string;   // or applicationName is required

  // Authentication
  getJwt?: () => Promise<string>;   // Recommended
  jwt?: string;

  // Display
  language?: 'en' | 'ko';
  screenshotMode?: 'fullpage' | 'viewport';
  appearance?: AppearanceInput;  // 'blue' | 'purple' | custom object
  displayMode?: 'chat' | 'headless';
  headless?: HeadlessConfig;

  // Behavior
  useVision?: boolean;
  observeTargetSelector?: string;
  pageSanitizationScript?: (document: Document) => void;
  enableSessionRecording?: boolean;
  enableScreenHistoryRecording?: boolean;

  // Privacy & redaction
  redactAllInputs?: boolean;
  redactionSelectors?: string[];
  userMetadata?: Record<string, string | number | boolean | string[]>;

  // Integrations
  onSupportTicket?: (handoff: SupportTicketHandoff) => Promise<SupportTicketOutcome>;

  // Session
  sessionConfig?: {
    inactivityTimeout?: number;
    maxSessionAge?: number;
    showNotification?: boolean;
  };

  // Debug
  logLevel?: LogLevel;
  debugMode?: boolean;

  // Stability
  stability?: StabilityConfig;
}
```

***

## AssistantButton Props

The `AssistantButton` component accepts optional props for customization:

```tsx theme={null}
<AssistantButton
  iconVariant="question"        // 'default' (Moss logo) or 'question' (? icon)
  iconUrl="/custom-icon.svg"    // Custom icon URL (overrides iconVariant)
  position={{ bottom: 20, right: 80 }}  // Button position in pixels
  onButtonClick={() => {}}      // Callback when button is clicked
/>
```

| Prop            | Type                               | Default                     | Description           |
| --------------- | ---------------------------------- | --------------------------- | --------------------- |
| `iconVariant`   | `'default' \| 'question'`          | `'question'`                | Built-in icon style   |
| `iconUrl`       | `string`                           | —                           | Custom icon image URL |
| `position`      | `{ bottom?, right?, top?, left? }` | `{ bottom: 20, right: 80 }` | Button position       |
| `onButtonClick` | `() => void`                       | —                           | Click callback        |

## Next Steps

<CardGroup cols={2}>
  <Card title="Advanced" icon="sliders" href="/en/sdk/advanced">
    Stability tuning, Shadow DOM, CSP headers
  </Card>

  <Card title="SDK Options" icon="list" href="/en/configurations/sdk-options">
    Full SDK configuration options
  </Card>
</CardGroup>