Skip to main content

Quickstart

Get a character talking in under 5 minutes. This guide uses the REST API to create a character, then connects via Socket.IO to have a text conversation.

Prerequisites​

1. Create a Character​

curl -X POST https://api.estuary-ai.com/api/v1/characters \
  -H "X-API-Key: est_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": {
      "name": "Atlas",
      "personality": "You are Atlas, a friendly and curious explorer who loves learning about people."
    }
  }'

Save the id from the response -- this is your character_id.

2. Connect via Socket.IO​

Install the Socket.IO client:

npm install socket.io-client

Connect to the /sdk namespace with your API key and character ID:

import { io } from "socket.io-client";

const socket = io("https://api.estuary-ai.com/sdk", {
  auth: {
    api_key: "est_your_api_key",
    character_id: "YOUR_CHARACTER_ID",
    player_id: "quickstart_user",
    audio_sample_rate: 24000,
  },
});

socket.on("connect", () => {
  console.log("Connected!");
});

socket.on("session_info", (data) => {
  console.log("Session started:", data.session_id);
});

socket.on("auth_error", (data) => {
  console.error("Auth failed:", data.error);
});

3. Send a Message​

socket.emit("text", {
  text: "Hey Atlas! Tell me something interesting.",
  textOnly: true,
});

4. Receive the Response​

The response streams as multiple bot_response events:

let responseBuffer = "";

socket.on("bot_response", (data) => {
  if (data.partial) {
    responseBuffer += data.text;
    process.stdout.write(data.text); // print as it streams
  }
  if (data.is_final) {
    console.log("\n\nFull response:", responseBuffer);
    responseBuffer = "";
  }
});

Full Example​

import { io } from "socket.io-client";

const socket = io("https://api.estuary-ai.com/sdk", {
  auth: {
    api_key: "est_your_api_key",
    character_id: "YOUR_CHARACTER_ID",
    player_id: "quickstart_user",
    audio_sample_rate: 24000,
  },
});

let responseBuffer = "";

socket.on("session_info", (data) => {
  console.log("Connected! Session:", data.session_id);

  // Send a message once connected
  socket.emit("text", {
    text: "Hey! What's the most interesting thing you know?",
    textOnly: true,
  });
});

socket.on("bot_response", (data) => {
  if (data.partial) {
    responseBuffer += data.text;
    process.stdout.write(data.text);
  }
  if (data.is_final) {
    console.log("\n");
    responseBuffer = "";
  }
});

socket.on("auth_error", (data) => {
  console.error("Auth failed:", data.error);
  process.exit(1);
});

Run it:

npx tsx quickstart.ts

What's Next?​

  • Add voice: Remove textOnly: true and add TTS by configuring a voice_preset on your character. See Conversation Protocol for voice events.
  • Add memory: Just keep talking. Memory is automatic -- the character remembers across sessions for the same player_id. See Memory System.
  • Add actions: Define actions on your character and handle action tags in responses. See Action Protocol.
  • Use an SDK: For richer integration, use the Web SDK or Lens Studio SDK.
  • REST API: Manage characters, read conversations, and query memory via the REST API.
Last updated