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")
apiKey	string	Your API key (starts with est_)
characterId	string	UUID of the AI character to connect to
playerId	string	Unique identifier for the end user

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	16000	Audio sample rate in Hz for microphone capture
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: 16000,
});

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();