@avis-ai/react-sdk

React components and hooks for integrating Avis AI chat into your application.

Demo: https://demo-ai.avi-s.in — try the chat live before integrating.

Getting Your API Key

Before you can use the SDK, you need an API key:

1. Log in to the Dashboard
2. Create a project — give it a name and configure your system prompt
3. Copy the API key — it's shown once when the project is created. Store it securely.

Use this API key in the apiKey prop when integrating the SDK.

Installation

npm install @avis-ai/react-sdk @avis-ai/sdk-js
# or
pnpm add @avis-ai/react-sdk @avis-ai/sdk-js
# or
yarn add @avis-ai/react-sdk @avis-ai/sdk-js

Requires: React 18+

Quick Start

import { AvisChat } from "@avis-ai/react-sdk";

export function MyChat() {
  return <AvisChat apiKey="your-api-key" />;
}

That's it. You get a complete chat UI with message bubbles, streaming responses, and input.

Making the Best Use of AvisChat

1. Only apiKey is required

Everything else has sensible defaults. You can drop in <AvisChat apiKey="..." /> and it works.

2. Persist conversations with sessionId

The backend stores the entire conversation under the sessionId you pass. When you pass the same sessionId again (e.g. after a page reload), the conversation continues with full context — the AI remembers everything.

How it works:

• Pass a sessionId → backend associates all messages with that ID
• Pass the same sessionId on next visit → backend loads that conversation, AI has full context
• Pass a new sessionId (or omit it) → new conversation, no prior context

To persist across reloads: store sessionId in localStorage (or your storage of choice) and pass it back when the user returns.

3. Choose the right API

| Use case | Use | |----------|-----| | Drop-in chat widget with built-in UI | <AvisChat /> | | Custom UI, need full control | useAvisChat | | Need to get sessionId from the SDK | useAvisChat (it returns sessionId) | | Managing sessionId yourself | Either — create it, pass it in, persist it |

Components

<AvisChat />

A ready-to-use chat widget with built-in UI. Supports light and dark themes, streaming, and conversation memory.

import { AvisChat } from "@avis-ai/react-sdk";

<AvisChat
  apiKey="your-api-key"
  model="gpt-4o"
  sessionId="optional-session-id"
  theme="light"
  autoFocus={true}
  className="my-chat"
/>

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|--------------| | apiKey | string | Yes* | — | Your Avis API key. Not required if client is passed. | | client | Avis | No | — | Pre-configured Avis instance. Use instead of apiKey for server proxy setups. | | model | string | No | "gpt-4o-mini" | Model to use (e.g. gpt-4o, gpt-4o-mini, llama3). | | sessionId | string | No | auto-generated | Conversation ID. The backend stores the entire chat under this ID. Pass the same ID on reload to continue the conversation with full context. | | theme | "light" \| "dark" | No | "light" | Visual theme. | | models | ModelOption[] | No | GPT-4o Mini, GPT-4o, GPT-4, etc. | Model options for the dropdown. Pass { value, label }[] to customize. | | showModelSelector | boolean | No | true | Show model dropdown (OpenRouter-style). Set to false to hide. | | autoFocus | boolean | No | false | Focus input on mount. | | className | string | No | — | Additional CSS class for the container. |

* Either apiKey or client is required. baseUrl is not configurable — the SDK uses the official Avis API endpoint.

Hooks

useAvisChat

Use the chat logic with your own UI. Returns messages, loading state, error, handlers, and sessionId (so you can persist it).

import { useAvisChat } from "@avis-ai/react-sdk";

function CustomChat() {
  const { sessionId, messages, sendMessage, isLoading, error, reset } = useAvisChat({
    apiKey: "your-api-key",
  });

  return (
    <div>
      {messages.map((m, i) => (
        <div key={i}>{m.role}: {m.content}</div>
      ))}
      <button onClick={() => sendMessage("Hello!")} disabled={isLoading}>
        Send
      </button>
      {error && <p>Error: {error.message}</p>}
      <button onClick={reset}>Reset</button>
    </div>
  );
}

Options

Same as AvisChat props: apiKey, client, model, sessionId.

Return Value

| Property | Type | Description | |----------|------|-------------| | sessionId | string | Current session ID. Persist this (e.g. to localStorage) and pass it back as sessionId on next load to continue the conversation. | | messages | AvisChatMessage[] | Conversation messages (role + content). | | sendMessage | (content: string) => Promise<void> | Send a user message and stream the assistant reply. | | isLoading | boolean | true while a response is streaming. | | error | Error \| null | Last error, if any. | | reset | () => void | Clear messages and error, start a new session (generates a new sessionId). |

Session Persistence (Step by Step)

The backend stores the entire conversation under the sessionId. To keep conversations across page reloads:

1. Create or load a sessionId — from localStorage, or generate a new one
2. Pass it to AvisChat or useAvisChat
3. Save it when it changes — so the next visit can load it

With AvisChat — you manage sessionId

Create it, persist it, pass it in. The component does not expose sessionId; you own it from the start.

function PersistentAvisChat() {
  const [sessionId] = useState(
    () => localStorage.getItem("avis-session") ?? crypto.randomUUID()
  );

  useEffect(() => {
    localStorage.setItem("avis-session", sessionId);
  }, [sessionId]);

  return <AvisChat apiKey="your-api-key" sessionId={sessionId} />;
}

With useAvisChat — the hook returns sessionId

The hook gives you sessionId; persist it and pass it back on load.

function PersistentCustomChat() {
  const [storedSessionId] = useState(
    () => localStorage.getItem("avis-session") ?? undefined
  );

  const { sessionId, messages, sendMessage, isLoading, error, reset } = useAvisChat({
    apiKey: "your-api-key",
    sessionId: storedSessionId,
  });

  useEffect(() => {
    if (sessionId) localStorage.setItem("avis-session", sessionId);
  }, [sessionId]);

  return (
    <div>
      {messages.map((m, i) => (
        <div key={i}>{m.role}: {m.content}</div>
      ))}
      <input onKeyDown={(e) => e.key === "Enter" && sendMessage((e.target as HTMLInputElement).value)} />
      {error && <p>{error.message}</p>}
      <button onClick={reset}>New conversation</button>
    </div>
  );
}

Complete Example: AvisChat with Persistence

import { useState, useEffect } from "react";
import { AvisChat } from "@avis-ai/react-sdk";

const STORAGE_KEY = "avis-chat-session";

export function MyPersistentChat() {
  const [sessionId, setSessionId] = useState(() => {
    if (typeof window === "undefined") return crypto.randomUUID();
    return localStorage.getItem(STORAGE_KEY) ?? crypto.randomUUID();
  });

  useEffect(() => {
    localStorage.setItem(STORAGE_KEY, sessionId);
  }, [sessionId]);

  return (
    <AvisChat
      apiKey={process.env.NEXT_PUBLIC_AVIS_API_KEY!}
      sessionId={sessionId}
      theme="light"
    />
  );
}

Using a Proxy (Recommended for Production)

To avoid exposing your API key in the browser, proxy requests through your backend. Your server forwards requests to the Avis API with the real API key.

Types

interface AvisChatMessage {
  role: "system" | "user" | "assistant";
  content: string;
}

Styling

AvisChat uses inline styles by default. Override layout with className and your own CSS:

.my-chat {
  height: 500px !important;
  max-height: 90vh !important;
}

The messages area uses .avis-chat-messages and has custom scrollbar styling for light/dark themes.