Quickstart

Integrate Navsi AI seamlessly into any React or Next.js application. Create an API key, install the SDK, configure your environment, and go live in under 5 minutes.

Prerequisites

Before you integrate, make sure your environment matches the criteria below.

Node.js 18 or later in the app you’re integrating.

A Navsi AI account to generate a live API key.

Any modern React environment (e.g., Next.js, Vite, Create React App).

A reachable Navsi server HTTP URL.

Get your API key

Your API key and server URL are provided during onboarding. Keep them out of source control.

Pro Tip

Navsi AI is currently in invite-only beta. Your live API key mapping will be distributed directly to your email.

Install the SDK

Install the core Navsi SDK package via pnpm (or your preferred package manager).

Terminal

pnpm install @navsi.ai/sdk

Add environment variables

Add the API key and server URL to your app's .env file.

.env

VITE_NAVSI_API_KEY=your_navsi_api_key
VITE_NAVSI_API_URL=https://your-navsi-server.example.com

Important

Never construct the WebSocket URL manually in production without routing it through your secure backend proxy if strict CORS is required.

Create ChatbotWrapper.tsx

Create a reusable wrapper to cleanly configure the provider, widget, environment variables, and any framework-specific routing adapters.

src/components/ChatbotWrapper.tsx

// src/components/ChatbotWrapper.tsx
import { ChatbotProvider, ChatbotWidget, useReactRouterAdapter } from '@navsi.ai/sdk';
import { useNavigate, useLocation } from 'react-router-dom';

function getWebSocketUrl(httpUrl: string): string {
  try {
    const url = new URL(httpUrl);
    const wsProtocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
    return `${wsProtocol}//${url.host}/ws`;
  } catch {
    return httpUrl.replace(/^https?:\/\//, (m) =>
      m === 'https://' ? 'wss://' : 'ws://'
    ) + '/ws';
  }
}

const API_KEY = import.meta.env.VITE_NAVSI_API_KEY || '';
const API_URL = import.meta.env.VITE_NAVSI_API_URL || '';
const WS_URL = getWebSocketUrl(API_URL);

interface ChatbotWrapperProps {
  children: React.ReactNode;
}

export function ChatbotWrapper({ children }: ChatbotWrapperProps) {
  const navigate = useNavigate();
  const location = useLocation();
  const navigationAdapter = useReactRouterAdapter(navigate, location);

  return (
    <ChatbotProvider
      apiKey={API_KEY}
      serverUrl={WS_URL}
      navigationAdapter={navigationAdapter}
      config={{
        headerTitle: 'Assistant',
        welcomeMessage: 'Hi! How can I help you today?',
        showModeToggle: true,
        defaultMode: 'ask',
      }}
    >
      {children}
      <ChatbotWidget />
    </ChatbotProvider>
  );
}

Wrap your application

Import the wrapper and place it globally around your application routes (e.g., in main.tsx for Vite, or layout.tsx for Next.js).

src/main.tsx

import { ChatbotWrapper } from './components/ChatbotWrapper.tsx';

// ... other imports ...

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <StoreProvider>
      <BrowserRouter>
        <ChatbotWrapper>
          <Routes>
            <Route path="/" element={<App />}>
              <Route index element={<BillingPage />} />
              <Route path="products" element={<ProductsPage />} />
              <Route path="reports" element={<ReportsPage />} />
            </Route>
          </Routes>
        </ChatbotWrapper>
      </BrowserRouter>
    </StoreProvider>
  </StrictMode>,
);

Verify the integration

Start your local dev server and confirm everything is wired up.

Widget renders with the header title Assistant.
WebSocket connection to your Navsi server succeeds in Network tab.

Next Steps

SDK Reference

Dive deep into ChatbotProvider and standalone hooks.

Contact Support

Reach out directly if you hit any blockers integration.