TypeScript types

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

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`

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

The state of the LiveKit room connection.

`AgentState`

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`

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`

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

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

Display & layout

`DisplayMode`

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

Used by <AvatarWidget>'s displayMode and defaultDisplayMode.

`WidgetPosition`

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`

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`

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`

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`

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`

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`

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

`TeamMember`

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

Used by <AvatarWidget>'s teamMembers prop.

`SoundEffectsConfig`

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

Toggle individual sound effects.

Routing

`RoutePattern`

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

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

Page awareness

`PageContext`

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`

interface SessionOptions {
  agentId: string;
  baseUrl?: string;
  apiKey?: string;
  sessionEndpoint?: string;
  sessionBody?: Record<string, unknown>;
}

Passed to useLiveKitSession() and new LiveKitSession().

`SessionCallbacks`

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;
  onResumabilityChange?: (canResume: boolean) => void;
}

The full callback set settable on a LiveKitSession instance. Used directly in vanilla SDK consumption; wrapped by useLiveKitSession for React.

Tracker

`TrackerConfig`

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

`VisitorInfo`

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

Returned by tracker.init().