What’s Included in This Demo

The repository contains three demo applications, all powered by the Perso Interactive Web SDK:

All demos connect to the same Perso Interactive API and follow the same session lifecycle.

📋 Prerequisites

Any demo requires API Key, create an account and API key using the Perso AI Platform.

Before running any demo, make sure you have:

• Node.js v20 or higher
• pnpm package manager

Install Node.js

nvm install 20

Install pnpm

npm install -g pnpm

🚀 Installing the SDK

Install the SDK using your preferred package manager:

npm install perso-interactive-sdk-web

yarn add perso-interactive-sdk-web

pnpm add perso-interactive-sdk-web

Installing Dependencies

At the repo root:

pnpm install

Build the SDK

pnpm build

Usage

Client-side (browser):

import {
  createSession,
  ChatTool,
  ChatState,
} from "perso-interactive-sdk-web/client";

Server-side (Node.js/SvelteKit/Next.js):

import { createSessionId, getIntroMessage } from "perso-interactive-sdk-web/server";

SvelteKit Demo

apps/svelte (@perso-interactive-sdk-web/app-svelte)

The SvelteKit demo demonstrates server-side session creation and is recommended if you need:

• Secure API key handling
• Session configuration
• SSR-compatible architecture

Configuration

Before running the demo, configure your API key.

Create .env file and set environment variable

PERSO_INTERACTIVE_API_KEY=YOUR_API_KEY

Or a constant file

// src/lib/constant.ts
export const persoInteractiveApiKey = "YOUR_API_KEY";

Session creation is handled on the server in:

src/routes/session/+server.ts

This endpoint:

1. Fetches available models and settings
2. Creates a Perso session ID
3. Returns the session ID to the client

Run it with:

pnpm svelte

The app starts on http://localhost:5173. When the page loads, a session is automatically created via the /session route and the avatar connects over WebRTC.

Next.JS Demo

apps/nextjs (@perso-interactive-sdk-web/app-nextjs)

The Next.js demo is a React-based example with server-side session creation via the App Router.

Use this demo if you want:

• A React integration with Next.js App Router
• Server-side API key protection
• A production-like reference for SDK usage

Configuration

Create a .env.local file in apps/nextjs/:

// .env.local
PERSO_INTERACTIVE_API_KEY = "YOUR API KEY";

Run it with:

pnpm nextjs

The app starts on http://localhost:5174. When the page loads, a session is automatically created via the /api/session route and the avatar connects over WebRTC.

Vanilla JavaScript Demo

apps/vanilla (@perso-interactive-sdk-web/app-vanilla)

The Vanilla demo is a minimal HTML + JavaScript example powered by Vite.

Use this demo if you want:

• The simplest possible integration
• No framework dependencies
• A quick reference for SDK usage

Run it with:

pnpm vanilla

The app starts on http://localhost:5173. When the page loads, enter your API server URL and API key, configure session settings, and press START to connect the avatar over WebRTC.

TypeScript Demo

apps/typescript (@perso-interactive-sdk-web/app-typescript)

The TypeScript demo is identical to the Vanilla demo in behavior and UI, but adds:

• Full SDK typings
• Compile-time safety
• Better IDE support

Run it with:

pnpm typescript

The app starts on http://localhost:5173. When the page loads, enter your API server URL and API key, configure session settings, and press START to connect the avatar over WebRTC.

Using the SDK in TypeScript

The Perso Interactive Web SDK ships with a global type definition file:

📄 perso-interactive-sdk.d.ts https://github.com/perso-ai/perso-interactive-sdk-web/blob/main/core/1.0.1/perso-interactive-sdk.d.ts

This file exposes the global PersoInteractive namespace (session helpers, ChatState, ChatTool, error classes, etc.).

The app starts on http://localhost:5173. When the page loads, enter your API server URL and API key, configure session settings, and press START to connect the avatar over WebRTC.

Enabling SDK Types

To enable typing in your TypeScript app, create or update an ambient declaration file with a triple-slash reference to the SDK d.ts.

// app.d.ts or global.d.ts
/// <reference types="/perso-interactive-sdk.d.ts" />

If you are using perso-interactive-sdk.d.ts in your project, copy the file and write reference at the top of app.d.ts or global.d.ts to gain typing access to PersoInteractive.

Available SDK Utilities

PersoUtil

Helper functions that wrap Perso REST APIs:

getLLMs

getModelStyles

getBackgroundImages

getTTSs

getSTTs

getPrompts

getDocuments

getMcpServers

getSessionInfo

sessionEvent

All helpers accept:

(apiServerUrl: string, apiKey: string)

and return typed JSON responses.

Session Helpers

createSessionId

getIntroMessage

These shared helpers that encapsulate the auth headers and payload format needed before the web client calls PersoInteractive.createSession.

Error Handling

The SDK provides an ApiError class for HTTP failures.

It includes:

status

code

detail

attr

Use this to map API errors to user-facing messages or retry logic.

Session Flow Overview

1. Collect the Perso Interactive API server URL and API key from the operator.
2. Call PersoInteractive.getAllSettings to fetch LLM, TTS/STT, model style, prompt, document, background, toolcalling and MCP server options for the UI.
3. When the user clicks START, invoke createSessionId with the selected options (plus optional padding, voice chat toggle, and client tool selections), then createSession to bind the media stream to a <video> element.
4. Subscribe to chat logs and chat states to render transcripts, voice/speech controls, and availability indicators. Use client tools for app-specific actions and handle SDK errors via the provided callbacks.

Quick Look

Server Side

1. Create Session ID

// Import from server subpath
import { createSessionId, getIntroMessage } from "perso-interactive-sdk-web/server";

// 1. Initialize SDK
const apiServerUrl = "https://live-api.perso.ai";
const apiKey = "YOUR API KEY";

// 2. Create session id with configuration
const sessionId = await createSessionId(apiServerUrl, apiKey, {
  using_stf_webrtc: true,
  model_style, // Selected model style
  prompt, // Selected prompt
  llm_type, // Selected LLM
  tts_type, // Selected TTS
  stt_type, // Selected STT
  document, // Selected document
  background_image, // Selected background
  mcp_servers, // Selected MCP servers
  padding_left,
  padding_top,
  padding_height,
});

// 3. Get intro message (optional)
const introMessage = await getIntroMessage(apiServerUrl, apiKey, prompt);

return { sessionId, introMessage };

2. Create Session WebRTC(Browser)

// Import from client subpath
import { createSession } from "perso-interactive-sdk-web/client";

// Create WebRTC session
const session = await createSession(
  apiServerUrl,
  sessionId,
  chatbotWidth,
  chatbotHeight,
  enableVoiceChat,
  introMessage ?? "",
  clientTools ?? [], // Refer to the following reference
);

Client Side

⚠️

Warning: Using createSessionId on the client side is not recommended. This exposes your API KEY in the browser, making it vulnerable to theft. If your API KEY is compromised due to client-side implementation, the SDK provider assumes no responsibility. For security, please use server-side session creation instead.

1. Create Session ID + Create Session WebRTC

// Import from client subpath
import {
  createSessionId,
  createSession,
  ChatTool,
  ChatState,
} from "perso-interactive-sdk-web/client";

// 1. Initialize SDK
const apiServerUrl = "https://live-api.perso.ai";
const apiKey = "YOUR API KEY";

// 2. Fetch features and get session id
const sessionId = await createSessionId(apiServerUrl, apiKey, {
  using_stf_webrtc: true,
  model_style, // Selected model style
  prompt, // Selected prompt
  llm_type, // Selected LLM
  tts_type, // Selected TTS
  stt_type, // Selected STT
  document, // Selected document
  background_image, // Selected background
  mcp_servers, // Selected MCP servers
  padding_left,
  padding_top,
  padding_height,
});

// 3. Create WebRTC Session
const session = await createSession(
  apiServerUrl,
  sessionId,
  chatbotWidth,
  chatbotHeight,
  enableVoiceChat,
  introMessage ?? "",
  clientTools ?? [], // Refer to the following reference
);

Tool Calling Example

Client-side tool calling allows the model to trigger application-specific actions.

A reference implementation can be found here:

🔗 Perso Interactive Web SDK Tool Calling→

Web SDK API Reference

For detailed API documentation, see this repository: