SDK Options

Overview

SDK configuration options allow you to customize Moss behavior directly in your application code. These settings override Dashboard defaults when specified, giving developers fine-grained control per deployment, environment, or user segment.

Priority reminder: SDK configuration options take precedence over Dashboard settings. When you configure an option in code, it will override the value set in the Dashboard. This allows developers to customize behavior per-deployment while using Dashboard settings as defaults.

Required Options

These options must be provided in the AgentProvider config:

import { AgentProvider, AssistantButton } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
}}>
  <AssistantButton />
</AgentProvider>

Option	Type	Description
`apiUrl`	`string`	Moss API endpoint URL
`applicationId`	`string`	Your unique application ID from the Dashboard
`userId`	`string`	Unique identifier for the current user
`getJwt`	`() => Promise<string>`	Function that returns a JWT token

The userId should be a stable identifier for your user. Avoid using PII (email, name) directly - use a hashed or anonymized identifier instead.

Common Options

These options are frequently used to customize SDK behavior:

Language

Set the UI language for the SDK interface.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  language: 'en',  // 'en', 'ko', or undefined for auto-detect
}}>
  <AssistantButton />
</AgentProvider>

Default: undefined (auto-detects browser language)

Leave undefined to automatically use the user’s browser language preference.

Vision

Enable or disable screenshot analysis capabilities.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  useVision: true,  // Enable visual context
}}>
  <AssistantButton />
</AgentProvider>

Default: true (from Dashboard)

Session Recording

Control whether user sessions are recorded for replay.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableSessionRecording: false,  // Disable for privacy-sensitive users
}}>
  <AssistantButton />
</AgentProvider>

Default: true (from Dashboard)

Screen History

Include user action history in AI context.

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  enableScreenHistoryRecording: true,
}}>
  <AssistantButton />
</AgentProvider>

Default: true (from Dashboard)

Appearance

Customize the visual theme of the Moss assistant UI.

Using Presets

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: 'blue',  // Use a preset theme
}}>
  <AssistantButton />
</AgentProvider>

Available presets:

Preset	Description
`'blue'`	Default blue theme with glassmorphism effects
`'purple'`	Purple theme with solid backgrounds

Custom Appearance

Override specific properties by passing a partial object:

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  appearance: {
    colors: {
      primary: '#3b82f6',
      primaryLight: '#60a5fa',
    },
    modal: {
      defaultPosition: { right: 20, bottom: 20 },
      defaultSize: { width: 400, height: 600 },
    },
    effects: {
      glassmorphism: true,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>

Customizable Properties

Category	Properties
`colors`	`primary`, `primaryLight`, `primaryLighter`, `userMessage`, `assistantMessage`, `headerBackground`, `inputAreaBackground`, `modalBackground`, `text.*`, `border`, `success`, `error`
`typography`	`fontFamily`, `fontSize.`, `lineHeight.`
`spacing`	`3xs`, `2xs`, `xs`, `sm`, `md`, etc.
`radius`	`sm`, `md`, `lg`, `xl`
`shadows`	`sm`, `md`, `lg`
`effects`	`glassmorphism`, `glassBlur`, `glassOpacity`
`inputBar`	`roundedTop`, `topShadow`
`progressBar`	`height`
`modal`	`defaultPosition`, `defaultSize`

Partial objects are deep-merged with the base theme. You only need to specify the properties you want to override.

Session Options

Configure session management behavior:

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  sessionConfig: {
    inactivityTimeout: 60,
    maxSessionAge: 4,
    showNotification: true,
  },
}}>
  <AssistantButton />
</AgentProvider>

Option	Type	Default	Description
`inactivityTimeout`	`number`	`30`	Minutes of inactivity before session expires
`maxSessionAge`	`number`	`2`	Maximum session duration in hours
`showNotification`	`boolean`	`true`	Show notification on new session

Developer Options

Advanced settings for debugging and customization:

Screenshot Mode

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  screenshotMode: 'viewport',  // 'fullpage' or 'viewport'
}}>
  <AssistantButton />
</AgentProvider>

Default: 'fullpage'

Value	Description
`fullpage`	Captures the entire scrollable page
`viewport`	Captures only the visible portion

Use viewport for apps with very long pages to reduce processing time.

Log Level

import { AgentProvider, AssistantButton, LogLevel } from '@viamoss/moss-sdk';

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  logLevel: LogLevel.DEBUG,  // DEBUG, INFO, WARN, ERROR, SILENT
}}>
  <AssistantButton />
</AgentProvider>

Default: LogLevel.INFO logLevel takes the LogLevel enum exported by the SDK, not a string. Each level includes everything more severe than itself (DEBUG shows everything, SILENT disables logging).

Debug Mode

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  debugMode: true,
}}>
  <AssistantButton />
</AgentProvider>

Default: false Enables verbose logging and debug features for troubleshooting.

DOM Target Selector

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  observeTargetSelector: '#main-content',
}}>
  <AssistantButton />
</AgentProvider>

Default: 'body' CSS selector for the DOM element to observe. Change this to limit observation to a specific part of your page.

DOM Stability

Configure how the SDK waits for the page to stabilize:

<AgentProvider config={{
  apiUrl: 'https://moss-api.viamoss.ai',
  applicationId: 'YOUR_APP_ID',
  userId: currentUser.id,
  getJwt: () => fetchMossToken(),
  stability: {
    maxTotalWaitMs: 15000,
    layers: {
      networkIdle: true,
      domMutations: true,
      loadingIndicators: false,
      frameReadiness: true,
      resourceQuiet: true,
      layoutShift: false,
      browserIdle: true,
      finalFrame: true,
    },
    domMutations: {
      quietPeriodMs: 1000,
    },
  },
}}>
  <AssistantButton />
</AgentProvider>

See the SDK Advanced Configuration guide for detailed layer-by-layer documentation.

Complete TypeScript Interface

Here’s the full TypeScript interface for SDK configuration:

interface MossConfig {
  // Required
  apiUrl: string;
  applicationId: string;
  userId: string;
  getJwt: () => Promise<string>;

  // Application Features
  useVision?: boolean;
  language?: 'en' | 'ko';
  appearance?: AppearanceInput;  // 'blue' | 'purple' | custom object

  // Recording & History
  enableSessionRecording?: boolean;
  enableScreenHistoryRecording?: boolean;

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

  // Technical Settings
  logLevel?: LogLevel;  // enum: DEBUG, INFO, WARN, ERROR, SILENT
  debugMode?: boolean;
  screenshotMode?: 'fullpage' | 'viewport';
  observeTargetSelector?: string;

  // DOM Stability
  stability?: {
    maxTotalWaitMs?: number;
    layers?: {
      networkIdle?: boolean;
      domMutations?: boolean;
      loadingIndicators?: boolean;
      frameReadiness?: boolean;
      resourceQuiet?: boolean;
      layoutShift?: boolean;
      browserIdle?: boolean;
      finalFrame?: boolean;
    };
    domMutations?: {
      quietPeriodMs?: number;
    };
  };
}

Settings Not Available in SDK

The following settings can only be configured through the Dashboard:

AI Assistant Instructions - Custom instructions for the AI
API Keys - Authentication credentials
Domain Access Control - Allowed domains list
Vector Store Configuration - RAG system settings

These settings are Dashboard-only for security reasons. They affect application-wide behavior and authentication.

Getting Started

SDK

Dashboard

Configuration

Security

Guides

Resources

Overview

Required Options

Common Options

Language

Vision

Session Recording

Screen History

Appearance

Using Presets

Custom Appearance

Customizable Properties

Session Options

Developer Options

Screenshot Mode

Log Level

Debug Mode

DOM Target Selector

DOM Stability

Complete TypeScript Interface

Settings Not Available in SDK

Next Steps

Examples

Dashboard Settings

​Overview

​Required Options

​Common Options

​Language

​Vision

​Session Recording

​Screen History

​Appearance

​Using Presets

​Custom Appearance

​Customizable Properties

​Session Options

​Developer Options

​Screenshot Mode

​Log Level

​Debug Mode

​DOM Target Selector

​DOM Stability

​Complete TypeScript Interface

​Settings Not Available in SDK

​Next Steps

Examples

Dashboard Settings

Overview

Required Options

Common Options

Language

Vision

Session Recording

Screen History

Appearance

Using Presets

Custom Appearance

Customizable Properties

Session Options

Developer Options

Screenshot Mode

Log Level

Debug Mode

DOM Target Selector

DOM Stability

Complete TypeScript Interface

Settings Not Available in SDK

Next Steps