live-layerdocs
View as markdown

TypeScript types

Every type the NPM packages export. Most are re-exported from @livelayer/sdk through @livelayer/react, so importing from either works.

ts
import type {
  AgentState,
  ConnectionState,
  TranscriptEntry,
  AgentConfig,
  AgentCommand,
  AgentCapability,
  AvatarWidgetProps,
  AvatarWidgetHandle,
  ControlledSession,
  DisplayMode,
  WidgetPosition,
  TeamMember,
  BrandingConfig,
  RoutePattern,
  PageContext,
  SoundEffectsConfig,
  AgentEventDetail,
  SessionOptions,
  SessionCallbacks,
  TrackerConfig,
  VisitorInfo,
} from "@livelayer/react";

Session lifecycle

ConnectionState

ts
type ConnectionState = "idle" | "connecting" | "connected" | "disconnected" | "error";

The state of the LiveKit room connection.

AgentState

ts
type AgentState = "idle" | "listening" | "thinking" | "speaking";

What the agent is doing right now. Drives UI cues like the "thinking" pulse and mic-active indicator.

TranscriptEntry

ts
interface TranscriptEntry {
  id: string;
  role: "agent" | "user";
  text: string;
  final: boolean;
}

A single transcript line. Partial entries (final: false) are streamed in as the speaker talks; the final version replaces them once the speaker finishes.

AgentConfig

ts
interface AgentConfig {
  name: string;
  avatarImageUrl: string;
  idleLoopUrl?: string;
}

Server-published agent metadata. Surfaced once the session connects.

Display & layout

DisplayMode

ts
type DisplayMode = "hidden" | "minimized" | "expanded";

Used by <AvatarWidget>'s displayMode and defaultDisplayMode.

WidgetPosition

ts
type WidgetPosition =
  | "top-left"
  | "top-right"
  | "bottom-left"
  | "bottom-right"
  | "custom";

Where the floating bubble docks. "custom" means "I'll position it myself with className / style."

Agent commands & events

AgentCommand

ts
type AgentCommand = {
  type: string;
  [key: string]: unknown;
};

An open union — anything the agent emits over its data channel. Universal commands (navigate, scroll_page, scroll_to, click, fill_field, submit_form) are handled by the widget; everything else gets surfaced via onAgentCommand for your app to handle.

AgentCapability

ts
type AgentCapability =
  | "navigate"
  | "scroll"
  | "click"
  | "fill_forms"
  | "submit_forms"
  | "read_page";

Allowlist for what the agent is permitted to do on your page. See Capabilities in <AvatarWidget>.

AgentEventDetail

ts
interface AgentEventDetail {
  eventName: string;
  data?: unknown;
}

The wrapper for every observability event surfaced to onAgentEvent. Use for analytics, logging, or piping to your own event bus.

Component props

AvatarWidgetProps

The full prop type for <AvatarWidget>. See the reference page for every field.

AvatarWidgetHandle

ts
interface AvatarWidgetHandle {
  sendData(data: Record<string, unknown>): Promise<void>;
}

Imperative methods exposed via forwardRef. Right now only sendData (publish over the LiveKit data channel).

ControlledSession

ts
interface ControlledSession {
  agentId: string;
  baseUrl?: string;
  connectionState: ConnectionState;
  agentState: AgentState;
  transcript: TranscriptEntry[];
  agentConfig: AgentConfig | null;
  videoElement: HTMLVideoElement | null;
  audioElement: HTMLAudioElement | null;
  canResume: boolean;
  error: string | null;
  connect(): Promise<void>;
  disconnect(): void;
  sendData?(data: Record<string, unknown>): Promise<void>;
  subscribeToDataMessages?(handler: (msg: Record<string, unknown>) => void): () => void;
}

Pass to <AvatarWidget>'s controlledSession prop when you own the session lifecycle. See Controlled session.

BrandingConfig

ts
interface BrandingConfig {
  logoUrl?: string;
  productName?: string;
  primaryColor?: string;
  accentColor?: string;
  backgroundColor?: string;
  textColor?: string;
}

TeamMember

ts
interface TeamMember {
  id: string;
  name: string;
  role?: string;
  avatarImageUrl?: string;
  previewVideoUrl?: string;
  agentId?: string;
}

Used by <AvatarWidget>'s teamMembers prop.

SoundEffectsConfig

ts
interface SoundEffectsConfig {
  chime?: boolean;
  confirmation?: boolean;
  thinking?: boolean;
}

Toggle individual sound effects.

Routing

RoutePattern

ts
type RoutePattern = string | RegExp | ((pathname: string) => boolean);

Used by showOn and hideOn. Strings support glob-style * (single segment) and ** (any depth).

Page awareness

PageContext

ts
interface PageContext {
  headings: Array<{ level: number; text: string }>;
  links: Array<{ href: string; text: string }>;
  visibleText: string;
  formFields: Array<{ name: string; label: string; type: string; required?: boolean }>;
  regions: Array<{ name: string; description?: string; text: string }>;
  extras?: Record<string, unknown>;
}

The DOM snapshot sent to the agent on request_page_context. Override extraction via getPageContext on <AvatarWidget>.

Session options

SessionOptions

ts
interface SessionOptions {
  agentId: string;
  baseUrl?: string;
  apiKey?: string;
  sessionEndpoint?: string;
  sessionBody?: Record<string, unknown>;
  automanifest?: boolean;      // default true: share the page's form fields with the agent
  publishMicrophone?: boolean; // default true; false when your code publishes the mic (0.9+)
}

Passed to useLiveKitSession() and new LiveKitSession().

SessionCallbacks

ts
interface SessionCallbacks {
  onConnectionStateChange: (state: ConnectionState) => void;
  onAgentStateChange: (state: AgentState) => void;
  onTranscript: (entries: TranscriptEntry[]) => void;
  onAgentConfig: (config: AgentConfig) => void;
  onAudioTrack: (audio: HTMLAudioElement) => void;
  onVideoTrack: (video: HTMLVideoElement) => void;
  onVideoTrackRemoved: () => void;
  onError: (message: string, code?: string) => void;
  onDataMessage?: (msg: Record<string, unknown>) => void; // agent only, no topic
  onAvatarEvent?: (
    msg: Record<string, unknown>,
    meta: { topic: string; participantIdentity: string },
  ) => void; // avatar's "lemonslice"-topic events (0.9+)
  onAvatarDisconnected?: (info: { identity: string; reason?: string }) => void; // 0.9+
  onResumabilityChange?: (canResume: boolean) => void;
}

The full callback set, passed as the second argument to new LiveKitSession(). The first eight are required. Used directly in vanilla SDK consumption; wrapped by useLiveKitSession for React.

Tracker

TrackerConfig

ts
interface TrackerConfig {
  agentId: string;
  apiBase?: string;
  autoTrack?: boolean;
  autoTrackClicks?: boolean;
}

VisitorInfo

ts
interface VisitorInfo {
  id: string;
  isReturning: boolean;
  sessionCount: number;
}

Returned by tracker.init().