Configuration

Complete reference for the EstuaryConfig interface, which controls all client behavior.

EstuaryConfig

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

Required Fields

Field	Type	Description
serverUrl	string	Base URL of the Estuary server (e.g., "https://api.estuary-ai.com")
characterId	string	UUID of the AI character to connect to
playerId	string	Unique identifier for the end user

Authentication (one of these is required)

Either apiKey or sessionToken must be provided. If neither is set, the constructor throws an EstuaryError with code AUTH_FAILED.

Field	Type	Description
apiKey	string	Your API key (starts with est_). Use this for first-party integrations where the server URL and key live in your own backend.
sessionToken	string	Session token from a share-link exchange (starts with sst_). Returned by EstuaryClient.openShare(). REST APIs (memory, character) are not available with session-token auth -- use a server-side proxy if you need them.

Optional Fields

Field	Type	Default	Description
voiceTransport	'websocket' | 'livekit' | 'auto'	'auto'	Voice transport to use. 'auto' prefers LiveKit if livekit-client is installed.
audioSampleRate	number	24000	Preferred TTS playback sample rate in Hz. Tells the server what rate to generate audio at. Use the default unless your platform requires a specific rate.
autoReconnect	boolean	true	Automatically reconnect on disconnect
maxReconnectAttempts	number	5	Maximum number of reconnection attempts before giving up
reconnectDelayMs	number	2000	Base delay in milliseconds between reconnect attempts. Actual delay increases with each attempt (delay * attemptNumber).
debug	boolean	false	Enable debug logging to the console
realtimeMemory	boolean	false	Enable memoryUpdated events after each response for live memory extraction notifications
suppressMicDuringPlayback	boolean	false	Mute microphone during TTS playback (software AEC fallback). Disables barge-in.
autoInterruptOnSpeech	boolean	true	Automatically interrupt bot audio when user starts speaking

Example Configurations

Minimal

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

Text-Only (No Voice)

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

// Use sendText with textOnly=true to suppress voice responses
await client.connect();
client.sendText('Hello!', true);

WebSocket Voice

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

Share Link (Session Token)

When opening a share link returned by EstuaryClient.openShare(), use sessionToken instead of apiKey:

const share = await EstuaryClient.openShare(
  'https://api.estuary-ai.com',
  'share-abc-123',
);

const client = new EstuaryClient({
  serverUrl: share.serverUrl,
  sessionToken: share.sessionToken,
  characterId: share.characterId,
  playerId: share.playerId,
});

LiveKit Voice

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

Aggressive Reconnection

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

No Reconnection

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

Debug Mode

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

When debug is true, the SDK logs detailed information to the console including connection state changes, events sent and received, and internal operations.

Real-Time Memory Events

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

client.on('memoryUpdated', (event) => {
  console.log(`Extracted ${event.memoriesExtracted} memories`);
});

Suppress Mic During Playback

const client = new EstuaryClient({
  serverUrl: 'https://api.estuary-ai.com',
  apiKey: 'est_your_api_key',
  characterId: 'your-character-uuid',
  playerId: 'user-123',
  suppressMicDuringPlayback: true,  // Mute mic while bot speaks
  autoInterruptOnSpeech: false,     // Disable auto-interrupt
});

Use suppressMicDuringPlayback as a software echo cancellation fallback on devices without hardware AEC. Note that this disables barge-in (the user cannot interrupt the bot by speaking).

Environment Tips

Browser

In browser environments, the SDK works out of the box. The AudioPlayer uses the Web Audio API (AudioContext) for playback, and getUserMedia for microphone access.

// Browser: just construct and connect
const client = new EstuaryClient({ /* ... */ });
await client.connect();
await client.startVoice(); // Prompts for microphone permission

Node.js

In Node.js, WebSocket and REST features (text chat, memory API) work. Voice features require a browser environment with getUserMedia and AudioContext support.

// Node.js: text chat and memory work
const client = new EstuaryClient({ /* ... */ });
await client.connect();
client.sendText('Hello!', true);

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