Skip to main content
Navsi AI

Quickstart

Use this quickstart to add Navsi AI to a Vite + React Router application. You'll create an API key, install the SDK, add environment variables, create a reusable wrapper, and verify the widget in a running app.

Before you begin#

  • Use Node.js 18 or later in the application you're integrating.
  • Create a Navsi AI account so you can generate a live API key.
  • Start from a frontend app that uses Vite and React Router, or adapt the same pattern to your router and build tooling.
  • Make sure your Navsi server has a reachable HTTP URL. The wrapper converts it to the matching WebSocket endpoint automatically.

1. Sign up and create an API key#

Create your Navsi AI account, then generate an API key in the dashboard. Use that key in your frontend integration, and keep it out of source control.

  1. 1. Sign up for Navsi AI.
  2. 2. In the dashboard, open API Keys.
  3. 3. Create a key and copy it immediately.
  4. 4. Store the key in your app's .env file instead of hardcoding it in code.
Access: account setup and API key provisioning are handled during onboarding.

2. Install the SDK#

Install the Navsi SDK in the app you're integrating. Older examples that also referenced @navsi.ai/shared are no longer needed.

Terminal
pnpm install @navsi.ai/sdk

3. Add environment variables#

In your app's .env file, add the Navsi API key and the Navsi server HTTP URL.

.env
VITE_NAVSI_API_KEY=your_navsi_api_keyVITE_NAVSI_API_URL=https://your-navsi-server.example.com

Why both values? VITE_NAVSI_API_KEY authenticates the widget, and VITE_NAVSI_API_URL is converted into the matching WebSocket URL inside the wrapper.

This is intentionally the integrated app's environment file, not this documentation site's environment configuration. Never commit live keys to source control.

4. Create ChatbotWrapper.tsx#

Create a reusable wrapper component so the provider, widget, routing adapter, and environment variables are configured in one place.

src/components/ChatbotWrapper.tsx
// src/components/ChatbotWrapper.tsximport { ChatbotProvider, ChatbotWidget, useReactRouterAdapter } from '@navsi.ai/sdk';import { useNavigate, useLocation } from 'react-router-dom'; // Convert HTTP URL to WebSocket URLfunction 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';  }} // Config from env varsconst 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>  );}

This example uses useReactRouterAdapter together with useNavigate and useLocation so the chatbot can navigate inside a React Router application.

5. Wrap your app in main.tsx#

Import the wrapper and place it around your routes so the chatbot is available throughout the application.

src/main.tsx
import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';import { BrowserRouter, Route, Routes } from 'react-router-dom';import './index.css';import App from './App.tsx';import { StoreProvider } from './context/StoreProvider.tsx';import { BillingPage } from './pages/BillingPage.tsx';import { ProductsPage } from './pages/ProductsPage.tsx';import { ReportsPage } from './pages/ReportsPage.tsx';import { ChatbotWrapper } from './components/ChatbotWrapper.tsx'; 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>,);

6. Verify the integration#

Integration complete

Start your application and confirm that the widget renders with the header title Assistant, shows the welcome message, and uses the React Router adapter for in-app navigation.

  • • Confirm the widget appears on every routed page wrapped by ChatbotWrapper.
  • • Confirm VITE_NAVSI_API_KEY and VITE_NAVSI_API_URL are loaded from your app's environment.
  • • Confirm the widget can open a websocket connection to your Navsi server.
  • • Test invalid or missing configuration values before you ship the integration to production.
API key management is provided as part of onboarding.
Back to docs home