JavaScript

Core SDK for browser and Node.js

Installation

npm install @ai-chans/sdk-js

Quick Start

import { ChansClient } from "@ai-chans/sdk-js"


const client = new ChansClient({
  agentToken: "agt_xxx", // From dashboard
  apiUrl: "https://api.chans.ai"
})


// Listen for events
client.on("transcript", (text) => console.log("User:", text))
client.on("response", (text) => console.log("Agent:", text))


// Connect (requests microphone permission)
await client.connect({ userId: "user-123" })


// Later: disconnect
await client.disconnect()

ChansClient

Constructor Options

OptionTypeRequiredDescription
agentTokenstringYesAgent token from dashboard (agt_xxx)
apiUrlstringNoAPI URL (default: https://api.chans.ai)
manualAudioHandlingbooleanNoHandle audio playback manually (for Node.js)

Methods

connect(options?)

Connects to the voice agent. Requests microphone permission in browser.

await client.connect({
  userId: "user-123" // Optional: for conversation segmentation
})

disconnect()

Disconnects from the voice agent.

await client.disconnect()

getState()

Returns current connection state.

const state = client.getState() // "idle" | "connecting" | "ready" | ...

isConnected()

Returns whether the client is connected.

if (client.isConnected()) {
  // ...
}

Events

Subscribe with client.on(event, callback). Returns an unsubscribe function.

EventCallbackDescription
stateChange(state: ChansState) => voidConnection state changed
transcript(text: string) => voidUser speech transcribed (interim)
userTurnComplete(text: string) => voidUser finished speaking (final)
response(text: string) => voidAgent response text
connected() => voidConnected to room
disconnected() => voidDisconnected from room
agentConnected(agent: AgentInfo) => voidAgent joined
agentDisconnected() => voidAgent left
error(error: Error) => voidError occurred
audioTrack(track: RemoteTrack) => voidAgent audio track available
const unsubscribe = client.on("transcript", (text) => {
  console.log("User said:", text)
})


// Later: stop listening
unsubscribe()

States

type ChansState =
  | "idle"        // Not connected
  | "connecting"  // Connecting to room
  | "waiting"     // Waiting for agent
  | "ready"       // Ready for conversation
  | "processing"  // Processing user speech
  | "speaking"    // Agent is speaking
  | "error"       // Error occurred

Node.js Usage

For Node.js, enable manual audio handling:

const client = new ChansClient({
  agentToken: "agt_xxx",
  manualAudioHandling: true
})


client.on("audioTrack", (track) => {
  // Handle audio track manually
})

Next