EstuaryClient

The main class for interacting with the Estuary platform. Manages the WebSocket connection, voice sessions, and provides access to the memory API.

import { EstuaryClient } from '@estuary-ai/sdk';

const client = new EstuaryClient(config);

Constructor

new EstuaryClient(config)

Creates a new client instance.

Parameter	Type	Description
config	EstuaryConfig	Client configuration

const client = new EstuaryClient({
  serverUrl: 'https://api.estuary-ai.com',
  apiKey: 'est_your_api_key',
  characterId: 'your-character-uuid',
  playerId: 'user-123',
});

---

Connection

connect()

Connects to the Estuary server and authenticates with the configured API key. Returns a promise that resolves with session info on success.

Returns: Promise<SessionInfo>

Throws: EstuaryError with code CONNECTION_FAILED or AUTH_FAILED

const session = await client.connect();
console.log('Session ID:', session.sessionId);

disconnect()

Disconnects from the server. Stops any active voice session, clears audio playback, and cleans up resources.

Returns: void

client.disconnect();

isConnected

Whether the client is currently connected and authenticated.

Type: boolean (read-only)

if (client.isConnected) {
  client.sendText('Hello!');
}

connectionState

The current connection state.

Type: ConnectionState (read-only)

console.log(client.connectionState); // 'connected', 'connecting', etc.

---

Text

sendText(text, textOnly?)

Sends a text message to the character.

Parameter	Type	Default	Description
text	string	--	The message text
textOnly	boolean	false	If true, suppresses voice response (text only)

Throws: EstuaryError with code NOT_CONNECTED

client.sendText('Hello!');
client.sendText('Summarize our chat', true); // no voice response

interrupt(messageId?)

Interrupts the current bot response and clears queued audio.

Parameter	Type	Description
messageId	string (optional)	Specific message to interrupt

Throws: EstuaryError with code NOT_CONNECTED

client.interrupt();
client.interrupt('msg-123');

---

Voice

startVoice()

Starts a voice session. Requests microphone permission and begins streaming audio to the server.

The voice transport used depends on the voiceTransport config option:

• 'websocket' -- Streams PCM audio over WebSocket
• 'livekit' -- Connects via LiveKit WebRTC (requires livekit-client)
• 'auto' (default) -- Uses LiveKit if available, otherwise WebSocket

Returns: Promise<void>

Throws:

• EstuaryError with code NOT_CONNECTED if not connected
• EstuaryError with code VOICE_ALREADY_ACTIVE if voice is already started
• EstuaryError with code VOICE_NOT_SUPPORTED if no transport is available
• EstuaryError with code MICROPHONE_DENIED if microphone permission is denied

await client.startVoice();

stopVoice()

Stops the active voice session. Releases the microphone and cleans up the voice manager.

Returns: void

client.stopVoice();

toggleMute()

Toggles the microphone mute state.

Throws: EstuaryError with code VOICE_NOT_ACTIVE if no voice session is active

Returns: void

client.toggleMute();

isMuted

Whether the microphone is currently muted.

Type: boolean (read-only)

console.log('Muted:', client.isMuted);

isVoiceActive

Whether a voice session is currently active.

Type: boolean (read-only)

if (client.isVoiceActive) {
  client.stopVoice();
}

---

Camera

sendCameraImage(imageBase64, mimeType, requestId?, text?)

Sends a camera image for vision-language model processing.

Parameter	Type	Description
imageBase64	string	Base64-encoded image data
mimeType	string	Image MIME type (e.g., 'image/jpeg')
requestId	string (optional)	Request ID (if responding to a cameraCaptureRequest)
text	string (optional)	Text to accompany the image

Throws: EstuaryError with code NOT_CONNECTED

client.sendCameraImage(base64Data, 'image/jpeg', requestId, 'What is this?');

updatePreferences(preferences)

Updates session-level preferences.

Parameter	Type	Description
preferences	object	Preferences to update
preferences.enableVisionAcknowledgment	boolean (optional)	Whether the character acknowledges before analyzing images

Throws: EstuaryError with code NOT_CONNECTED

client.updatePreferences({ enableVisionAcknowledgment: false });

---

Audio

notifyAudioPlaybackComplete(messageId?)

Notifies the server that audio playback has completed for a message. This is called automatically by the built-in AudioPlayer, but you can call it manually if implementing custom audio playback.

Parameter	Type	Description
messageId	string (optional)	The message whose audio finished playing

Throws: EstuaryError with code NOT_CONNECTED

client.notifyAudioPlaybackComplete('msg-123');

---

Properties

memory

The memory API client for querying memories, knowledge graphs, and facts.

Type: MemoryClient (read-only)

const facts = await client.memory.getCoreFacts();

See Memory & Knowledge Graph for usage details.

session

The current session info. null if not connected.

Type: SessionInfo | null (read-only)

if (client.session) {
  console.log('Conversation:', client.session.conversationId);
}

---

Event Methods

EstuaryClient extends TypedEventEmitter and provides typed event subscription:

on(event, listener)

Subscribe to an event. See Events and Types for the full event map.

client.on('botResponse', (response) => { /* ... */ });

off(event, listener)

Remove an event listener.

client.off('botResponse', handler);

once(event, listener)

Subscribe to an event for a single invocation.

client.once('connected', (session) => { /* ... */ });