Skip to main content

Getting Started

Get up and running with the Estuary Web SDK in minutes. This guide walks you through installation, configuration, and sending your first message to an AI character.

Prerequisites​

Before you begin, ensure you have:

RequirementDetails
Node.js18 or later
Estuary AccountSign up at app.estuary-ai.com
API KeyGenerated from your Estuary dashboard (starts with est_)
Character IDThe UUID of your AI character

Installation​

Install the SDK from npm:

npm install @estuary-ai/sdk

Or with other package managers:

yarn add @estuary-ai/sdk
pnpm add @estuary-ai/sdk

Quick Start​

Here is a minimal example that connects to a character and exchanges text messages:

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

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

// Listen for bot responses
client.on('botResponse', (response) => {
  if (response.isFinal) {
    console.log('Bot:', response.text);
  }
});

// Listen for errors
client.on('error', (err) => {
  console.error('Error:', err.message);
});

// Connect and send a message
async function main() {
  const session = await client.connect();
  console.log('Connected! Session:', session.sessionId);

  client.sendText('Hello! Tell me about yourself.');
}

main().catch(console.error);

Framework Integration (React / Next.js)​

The SDK uses browser APIs (WebSocket, AudioContext, getUserMedia), so it cannot run during server-side rendering. In a React or Next.js project:

// In Next.js App Router, mark your component as a client component:
"use client";

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

If you use next/dynamic with ssr: false, the page that calls it must also be a client component in Next.js 16+:

"use client";
import dynamic from "next/dynamic";

const Chat = dynamic(() => import("@/components/Chat"), { ssr: false });
tip

Always clean up the client on component unmount to avoid connection leaks:

useEffect(() => {
  return () => {
    client.disconnect();
  };
}, []);

What Happens Under the Hood​

  1. client.connect() opens a WebSocket connection to the Estuary server, authenticates with your API key, and returns a SessionInfo object.
  2. client.sendText() sends your message over the WebSocket.
  3. The server processes your message through the AI pipeline and streams the response back.
  4. The botResponse event fires for each chunk of the response. When isFinal is true, the full response text is available.

Complete Example​

This example demonstrates connection lifecycle handling, streaming responses, and cleanup:

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

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

// Connection events
client.on('connected', (session) => {
  console.log('Connected! Conversation:', session.conversationId);
});

client.on('disconnected', (reason) => {
  console.log('Disconnected:', reason);
});

client.on('reconnecting', (attempt) => {
  console.log(`Reconnecting (attempt ${attempt})...`);
});

// Response events
client.on('botResponse', (response) => {
  if (response.isFinal) {
    console.log('Bot:', response.text);
  } else {
    process.stdout.write(response.partial);
  }
});

// Error handling
client.on('error', (err) => {
  console.error('Error:', err.message);
});

client.on('authError', (message) => {
  console.error('Authentication failed:', message);
});

client.on('quotaExceeded', (data) => {
  console.warn(`Quota exceeded: ${data.message} (${data.current}/${data.limit})`);
});

// Main flow
async function main() {
  try {
    await client.connect();
    client.sendText('Hello!');
  } catch (err) {
    console.error('Failed to connect:', err);
  }
}

main();

// Clean up on exit
process.on('SIGINT', () => {
  client.disconnect();
  process.exit(0);
});

Next Steps​

Now that you have a working connection:

Last updated