ScenaroSession - Scenaro

ScenaroSession is the framework-agnostic core of the SDK. useScenaroSession is a thin React binding over it — if you’re not using React (vanilla JS, Vue, Svelte…), use this class directly.

import { ScenaroSession } from '@scenaro/sdk';

const session = new ScenaroSession({ apiUrl: 'https://api.scenaro.io' });

session.on('status-change', (status) => console.log(status));
session.on('message', (message) => render(message));

await session.start({
  scenario: 'publication-uuid',
  tools: {
    search_products: async ({ query }) => searchCatalog(query),
  },
});

Constructor

new ScenaroSession(options: ScenaroSessionOptions)

Option	Type	Default	Description
`apiUrl`	`string`	—	API base URL (or pass `client`)
`client`	`ScenaroClient`	—	Pre-built client instance
`apiPathPrefix`	`string`	`'/v1'`	Prepended to all endpoints
`storagePrefix`	`string`	`''`	Prefix for localStorage keys
`storage`	`StorageAdapter \| null`	`localStorage`	Custom storage adapter
`transport`	`Transport`	`LiveKitTransport`	Internal, non-public interface — injectable for tests

Throws if neither client nor apiUrl is provided.

State

All state is readable synchronously; changes are announced through events.

Getter	Type
`status`	`'idle' \| 'connecting' \| 'connected' \| 'reconnecting' \| 'ended'`
`agentState`	`'idle' \| 'listening' \| 'thinking' \| 'speaking'`
`messages`	`ConversationMessage[]`
`config`	`SessionConfig \| null`
`rawConfig`	`ConfigPayload \| null` — wire format (`restore_state`, tool wiring)
`conversationId`	`string \| null`
`room`	`unknown` — engine extension (LiveKit today), see Transport extensions

Methods

start

start(options: StartSessionOptions): Promise<void>

Identifies the visitor, starts a session, registers tools, and connects Transport. Throws ScenaroError with code IDENTIFY_FAILED or SESSION_START_FAILED.

StartSessionOptions

Field	Type	Default
`scenario`	`string`	required
`language`	`string`	scenario’s configured language
`inputMode` / `outputMode`	`'audio' \| 'text'`	`'audio'`
`microphone`	`boolean`	`true`
`externalId`	`string \| null`	auto-generated
`resumeConversationId`	`string`	—
`metadata`	`Record<string, unknown>`	—
`tools`	`Record<string, ToolHandler>`	`{}`

end

end(): Promise<void>

Unregisters tools, disconnects Transport, and sets status to 'ended'. The session can be started again with start().

sendText / setMicrophoneEnabled

sendText(text: string): Promise<void>
setMicrophoneEnabled(enabled: boolean): Promise<void>

In-session actions never throw — failures are emitted on the error event instead, so fire-and-forget call sites don’t produce unhandled rejections.

destroy

destroy(): void

Releases Transport listeners and timers. Call when the owning scope is torn down (ScenaroProvider does this automatically on unmount).

Events

Kebab-case event names, subscribed with on / off:

Event	Payload
`status-change`	`SessionStatus`
`agent-state`	`AgentState`
`message`	`ConversationMessage`
`config`	`SessionConfig`
`session-end`	`{ reason: string }` — `'shutdown'`, `'agent_disconnected'`, `'transport_disconnected'`
`error`	`ScenaroError`

Errors

class ScenaroError extends Error {
  code: 'IDENTIFY_FAILED' | 'SESSION_START_FAILED' | 'CONNECTION_LOST'
      | 'MIC_PERMISSION_DENIED' | 'TOOL_TIMEOUT' | 'AGENT_UNAVAILABLE';
  cause?: unknown;
}

start() throws; everything after connection emits on error instead.

SessionConfig

A curated view of the scenario config — backend plumbing (company_id, voice_stack, timestamps, tool wiring) is deliberately not exposed.

interface SessionConfig {
  features: SessionFeature[];       // { name, type, settings }
  collections: Collection[];        // typed — see @scenaro/sdk/protocol
  avatarEnabled: boolean;
  audioDictationEnabled: boolean;
}

​Constructor

​State

​Methods

​start

​StartSessionOptions

​end

​sendText / setMicrophoneEnabled

​destroy

​Events

​Errors

​SessionConfig