Installation

Choose the integration method that fits your application.

You’ll need your Application ID from the Moss Dashboard. You’ll also need a JWT signing key — see Authentication.

NPM Package (React)

For React 17+ applications.

Install

npm install @viamoss/moss-sdk

Basic Setup

Add AgentProvider and AssistantButton to your app. The provider does not need to wrap your entire application — just the Moss components.

App.tsx

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

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

AgentProvider only needs to wrap the Moss UI components (AssistantButton). It observes the full page DOM regardless of where it sits in the React tree.

Peer Dependencies

The SDK requires React 17 or 18 as a peer dependency:

{
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0",
    "react-dom": "^17.0.0 || ^18.0.0"
  }
}

CDN Script Tag

For any web application, regardless of framework.

Basic Setup

Add the script tag to your HTML. The SDK auto-initializes and renders the assistant button.

<script
  src="https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID&userId=USER_ID"
  data-api-base="https://moss-api.viamoss.ai"
></script>

Configuration via JavaScript

For more control, configure via window.mossSettings before the script loads:

<script>
  window.mossSettings = {
    apiUrl: 'https://moss-api.viamoss.ai',
    userId: 'user-123',
    jwt: 'YOUR_JWT_TOKEN',
    language: 'en',
  };
</script>
<script src="https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID"></script>

Global API

After initialization, a global window.MossSDK object is available:

// Reinitialize with new config
await window.MossSDK.boot({ userId: 'new-user' });

// Update user identity (triggers reinitialization)
window.MossSDK.identify('user-456', { plan: 'premium' });

// Update config at runtime
window.MossSDK.updateConfig({ language: 'ko' });

// Tear down completely
window.MossSDK.shutdown();

Custom Triggers

Open the assistant from any element using the data-moss-trigger attribute — no hooks required.

<button data-moss-trigger>Need Help?</button>

This works with any element: buttons, links, nav items, or custom components. The SDK listens for clicks on elements with this attribute and toggles the chat modal.

Examples

<!-- Navigation help button -->
<nav>
  <a href="/dashboard">Dashboard</a>
  <button data-moss-trigger>Help</button>
</nav>

<!-- Contextual help link -->
<div class="form-field">
  <label>API Key</label>
  <input type="text" name="apiKey" />
  <span data-moss-trigger class="help-link">How do I find my API key?</span>
</div>

React Component

function HelpButton() {
  return (
    <button data-moss-trigger className="custom-help-btn">
      Get Assistance
    </button>
  );
}

The attribute works inside React components without needing useAgent(). Useful for simple triggers without state management.

Without AssistantButton

You can use custom triggers instead of the built-in button:

<AgentProvider config={config}>
  {/* Custom trigger only - no AssistantButton */}
  <nav>
    <button data-moss-trigger>Help</button>
  </nav>
  <YourApp />
</AgentProvider>

TypeScript Constant

The SDK exports the attribute name for programmatic use:

import { MOSS_TRIGGER_ATTR } from '@viamoss/moss-sdk';

// MOSS_TRIGGER_ATTR = 'data-moss-trigger'
<button {...{ [MOSS_TRIGGER_ATTR]: true }}>Help</button>

Framework Examples

Next.js (App Router)
Next.js (Script Tag)
Vue.js
Angular

app/layout.tsx

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

export default async function RootLayout({ children }) {
  const session = await auth();

  return (
    <html>
      <body>
        {children}
        <MossAssistant userId={session.user.id} />
      </body>
    </html>
  );
}

// Client component for Moss
'use client';
function MossAssistant({ userId }: { userId: string }) {
  return (
    <AgentProvider config={{
      apiUrl: 'https://moss-api.viamoss.ai',
      applicationId: 'YOUR_APP_ID',
      userId,
      getJwt: () => fetch('/api/moss-token').then(r => r.json()).then(d => d.token),
    }}>
      <AssistantButton />
    </AgentProvider>
  );
}

app/layout.tsx

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID&userId=USER_ID"
          data-api-base="https://moss-api.viamoss.ai"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

App.vue

<script setup>
import { onMounted, onUnmounted } from 'vue';

let script = null;

onMounted(() => {
  window.mossSettings = {
    apiUrl: 'https://moss-api.viamoss.ai',
    userId: 'USER_ID',
    jwt: 'YOUR_JWT_TOKEN',
  };

  script = document.createElement('script');
  script.src = 'https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID';
  script.async = true;
  document.head.appendChild(script);
});

onUnmounted(() => {
  if (script && document.head.contains(script)) {
    document.head.removeChild(script);
  }
});
</script>

app.component.ts

import { Component, OnInit, OnDestroy } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements OnInit, OnDestroy {
  private script: HTMLScriptElement | null = null;

  ngOnInit() {
    (window as any).mossSettings = {
      apiUrl: 'https://moss-api.viamoss.ai',
      userId: 'USER_ID',
      jwt: 'YOUR_JWT_TOKEN',
    };

    this.script = document.createElement('script');
    this.script.src = 'https://cdn.viamoss.ai/moss-sdk@latest.min.js?applicationId=YOUR_APP_ID';
    this.script.async = true;
    document.head.appendChild(this.script);
  }

  ngOnDestroy() {
    if (this.script && document.head.contains(this.script)) {
      document.head.removeChild(this.script);
    }
  }
}

Getting Started

SDK

Dashboard

Configuration

Security

Guides

Resources

Installation

Installation

NPM Package (React)

Install

Basic Setup

Peer Dependencies

CDN Script Tag

Basic Setup

Configuration via JavaScript

Global API

Custom Triggers

Examples

React Component

Without AssistantButton

TypeScript Constant

Framework Examples

Next Steps

Authentication

Configuration

​Installation

​NPM Package (React)

​Install

​Basic Setup

​Peer Dependencies

​CDN Script Tag

​Basic Setup

​Configuration via JavaScript

​Global API

​Custom Triggers

​Examples

​React Component

​Without AssistantButton

​TypeScript Constant

​Framework Examples

​Next Steps

Authentication

Configuration

Installation

NPM Package (React)

Install

Basic Setup

Peer Dependencies

CDN Script Tag

Basic Setup

Configuration via JavaScript

Global API

Custom Triggers

Examples

React Component

Without AssistantButton

TypeScript Constant

Framework Examples

Next Steps