Getting Started

Install the SDK, set up your project, and verify everything works — in under 5 minutes.

What is Xpectrum SDK?

@xpectrum/sdk is a JavaScript/TypeScript library that lets you add AI-powered chat and AI voice calls to any website or app. Think of it as a bridge between your frontend and Xpectrum's AI servers.

Module	What it does	Import
Chat	Send messages, get streaming AI responses, manage conversations	@xpectrum/sdk/chat
Voice	Real-time voice calls with AI agents via WebRTC	@xpectrum/sdk/voice
Widgets	Pre-built floating UI (chat bubble, voice button)	@xpectrum/sdk/widgets

You can use any module independently — you don't need Voice to use Chat, and vice versa.

How It Works

text

Your App (Frontend)                     Xpectrum Server (Backend)
┌────────────────────┐                 ┌─────────────────────────┐
│                    │                 │                         │
│  import { ... }    │   HTTP + SSE    │  Chat API               │
│  from '@xpectrum/  │ ──────────────> │  POST /chat-messages    │
│        sdk'        │                 │  GET  /conversations    │
│                    │                 │                         │
│  XpectrumChat()    │   WebRTC        │  Voice Server           │
│  XpectrumVoice()   │ ──────────────> │  POST /tokens/generate  │
│                    │                 │  LiveKit (audio)        │
└────────────────────┘                 └─────────────────────────┘

You install the SDK in your frontend project
You provide your API key and server URL
The SDK handles all communication with Xpectrum servers
You receive callbacks/events with AI responses in real-time

Prerequisites

Node.js 18+ installed
npm, yarn, or pnpm
A Xpectrum account with:
- A Chat API key (looks like app-xxxxxxxxxxxx)
- A Chat base URL (like https://app.yourserver.com/api/v1)
- (For voice) A Voice API key, Voice base URL, and Agent name/UUID

Installation

npm / yarn / pnpm

bash

# npm
npm install @xpectrum/sdk

# yarn
yarn add @xpectrum/sdk

# pnpm
pnpm add @xpectrum/sdk

ℹ Peer dependency

livekit-client (required for voice) is included automatically as a dependency. No extra install needed.

CDN (Script Tag)

For plain HTML pages without a build step:

html

<script src="https://unpkg.com/@xpectrum/sdk/dist/xpectrum-sdk.umd.min.js"></script>
<script>
  // Everything is available on window.XpectrumSDK
  const chat = new XpectrumSDK.XpectrumChat({ ... });
  const voice = new XpectrumSDK.XpectrumVoice({ ... });
</script>

Project Setup — React (Vite)

bash

# 1. Create a new Vite + React + TypeScript project
npm create vite@latest my-xpectrum-app -- --template react-ts
cd my-xpectrum-app

# 2. Install dependencies
npm install

# 3. Install the Xpectrum SDK
npm install @xpectrum/sdk

# 4. Create your environment file
touch .env

Add your credentials to .env:

.env

VITE_CHAT_BASE_URL=https://app.yourserver.com/api/v1
VITE_CHAT_API_KEY=app-xxxxxxxxxxxx
VITE_VOICE_BASE_URL=https://api.xpectrum.co/
VITE_VOICE_API_KEY=xpectrum_ai_sk_xxxxxxxxxxxx
VITE_VOICE_AGENT_NAME=your-agent-uuid-here

⚠ Why VITE_ prefix?

Vite only exposes environment variables that start with VITE_ to the browser. This is a security feature — variables without the prefix are server-only.

Project Setup — Next.js (App Router)

bash

# 1. Create a new Next.js project
npx create-next-app@latest my-xpectrum-app --typescript --app --tailwind
cd my-xpectrum-app

# 2. Install the Xpectrum SDK
npm install @xpectrum/sdk

# 3. Create your environment file
touch .env.local

Add your credentials to .env.local:

.env.local

NEXT_PUBLIC_CHAT_BASE_URL=https://app.yourserver.com/api/v1
NEXT_PUBLIC_CHAT_API_KEY=app-xxxxxxxxxxxx
NEXT_PUBLIC_VOICE_BASE_URL=https://api.xpectrum.co/
NEXT_PUBLIC_VOICE_API_KEY=xpectrum_ai_sk_xxxxxxxxxxxx
NEXT_PUBLIC_VOICE_AGENT_NAME=your-agent-uuid-here

⚠ Why NEXT_PUBLIC_ prefix?

Next.js only exposes env vars starting with NEXT_PUBLIC_ to the browser. Without this prefix, the variable is only available on the server side.

⚠ Security

Add .env.local to your .gitignore! Never commit API keys to version control.

Environment Variables Reference

Property	Type	Required	Default	Description
*_CHAT_BASE_URL	string	Yes	—	Your Xpectrum Chat API endpoint (e.g. https://app.yourserver.com/api/v1)
*_CHAT_API_KEY	string	Yes	—	Bearer token for chat auth. From your Xpectrum admin panel.
*_VOICE_BASE_URL	string	No	—	Your Voice server (FastAPI) endpoint. Required for voice only.
*_VOICE_API_KEY	string	No	—	API key for voice auth (x-api-key header). Required for voice only.
*_VOICE_AGENT_NAME	string	No	—	Agent UUID or name to connect to. Required for voice only.

Replace * with your framework prefix: VITE_ (Vite), NEXT_PUBLIC_ (Next.js), REACT_APP_ (CRA).

Authentication

No token exchange or OAuth flow needed. You just provide your keys at init time and the SDK includes them on every request:

Module	Header Sent
Chat	Authorization: Bearer {apiKey}
Voice	x-api-key: {apiKey}

Verify Your Setup

Here's a minimal test to verify the SDK is installed and your credentials work. Create this component:

Next.js (App Router)

app/page.tsx

'use client';

import { useEffect, useState } from 'react';
import { XpectrumChat } from '@xpectrum/sdk';

export default function Home() {
  const [status, setStatus] = useState('Testing connection...');

  useEffect(() => {
    const chat = new XpectrumChat({
      baseUrl: process.env.NEXT_PUBLIC_CHAT_BASE_URL!,
      apiKey: process.env.NEXT_PUBLIC_CHAT_API_KEY!,
    });

    chat.getAppInfo()
      .then((info) => setStatus(`Connected! App: "${info.title}"`))
      .catch((err) => setStatus(`Error: ${err.message}`));

    return () => chat.destroy();
  }, []);

  return <div style={{ padding: 40, fontSize: 18 }}>{status}</div>;
}

React (Vite)

src/App.tsx

import { useEffect, useState } from 'react';
import { XpectrumChat } from '@xpectrum/sdk';

function App() {
  const [status, setStatus] = useState('Testing connection...');

  useEffect(() => {
    const chat = new XpectrumChat({
      baseUrl: import.meta.env.VITE_CHAT_BASE_URL,
      apiKey: import.meta.env.VITE_CHAT_API_KEY,
    });

    chat.getAppInfo()
      .then((info) => setStatus(`Connected! App: "${info.title}"`))
      .catch((err) => setStatus(`Error: ${err.message}`));

    return () => chat.destroy();
  }, []);

  return <div style={{ padding: 40, fontSize: 18 }}>{status}</div>;
}

export default App;

✓ Success

If you see "Connected! App: ..." — you're all set! Move on to the Chat or Voice guides.

⚠ Got an error?

401 — Check your API key
Network Error — Check your base URL
Module not found — Run npm install @xpectrum/sdk