Sessions and modes

A session is a server-issued realtime context (sessionId) that scopes rate limiting, conversation history, and audio routing. Every action — readAloud, sendBrowserAction, voice call, listener subscription — runs inside a session.

Modes

Mode	Used for	Audio routing
text	Pure text chat	None
audio_playback	TTS / read-aloud / non-call voice replies	Streamed over the channel WebSocket
voice_conversation	Full two-way WebRTC voice	SIP leg via the WebRTC gateway
listen	Interpretation listener — subscribe to a TelPhi stream	Streamed over the channel WebSocket
browser_actions	Pure BOA dispatch with no AI conversation	n/a

Find-or-create per endpointId + mode

The SDK keeps one session per (endpointId, mode) pair. Subsequent calls with the same pair reuse the existing WebSocket and the same endpoint can run multiple modes side by side (for example, a voice_conversation speaker and a listen subscriber on the same endpoint during interpretation).

// First call opens the session
await delphi.readAloud('Hello', {endpointId});

// Same (endpointId, mode='audio_playback') — reuses the WebSocket
await delphi.readAloud('Are you there?', {endpointId});

// Different mode — opens a separate session for the same endpoint
await delphi.startCall({endpointId, autoDial: true});

Closing sessions

// Close just the audio-playback session
await delphi.endSession(endpointId, 'audio_playback');

// Close every mode for an endpoint
await delphi.endSession(endpointId);

// Close everything the client has open
await delphi.endAllSessions();

Mode-keyed lookups

getSession(endpointId) returns an arbitrary match when multiple modes are open. Pass getSession(endpointId, mode) whenever your app may have more than one mode active for the same endpoint.

Idle timeout

Non-voice sessions auto-close after sessionIdleTimeoutMs (default 300_000 = 5 minutes). The clock resets on every outbound send and every inbound message. Set the value to 0 to disable.

Voice sessions ignore the timeout — they live until you explicitly hang up via endCall().

Session state shape

Each SessionClient exposes a small state object suitable for useSyncExternalStore:

const state = session.getState();
// { sessionId, mode, connected, lastActivityAt, lastMessage, ... }

session.subscribe(() => {
  // re-render on state change
});

The orchestrator-level state on DelphiClient aggregates this for all open sessions:

const state = delphi.getState();
state.sessions; // [{ endpointId, sessionId, mode, connected, lastActivityAt }]
state.voiceCall; // { inCall, calling, registered, telproDomain, ... }

Next step

Configuration — the DelphiClient constructor options that shape session and call behavior.