Configuration

All SDK options and their defaults.

Required Fields

Every SDK initialization requires these fields:

<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

You can provide applicationName instead of applicationId if preferred. At least one is required.

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

<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.

Integrations

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

Session Management

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 for details.

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

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:

<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

Getting Started

SDK

Dashboard

Configuration

Security

Guides

Resources

Configuration

Configuration

Required Fields

Common Options

All Options

Authentication

Display

Behavior

Privacy & Redaction

Integrations

Session Management

Debug

Stability

Full TypeScript Interface

AssistantButton Props

Next Steps

Advanced

SDK Options

​Configuration

​Required Fields

​Common Options

​All Options

​Authentication

​Display

​Behavior

​Privacy & Redaction

​Integrations

​Session Management

​Debug

​Stability

​Full TypeScript Interface

​AssistantButton Props

​Next Steps

Advanced

SDK Options

Configuration

Required Fields

Common Options

All Options

Authentication

Display

Behavior

Privacy & Redaction

Integrations

Session Management

Debug

Stability

Full TypeScript Interface

AssistantButton Props

Next Steps