Web/React SDK

The @echoai/web package lets you add voice AI to any web application. It provides a vanilla JavaScript client and React hooks/components.

Installation

npm install @echoai/web
# or
pnpm add @echoai/web

Vanilla JavaScript

import { EchoAI } from "@echoai/web";

const echoai = new EchoAI({
  apiUrl: "http://localhost:8000",
  token: "your-jwt-or-api-key",
});

// Start a voice session
await echoai.connect({
  assistantId: "optional-assistant-id",
});

// Listen for events
echoai.on("transcript", (text, isFinal) => {
  console.log(isFinal ? "Final:" : "Partial:", text);
});

echoai.on("agentSpeaking", (text) => {
  console.log("Agent:", text);
});

// Disconnect
echoai.disconnect();

React Hook: useEchoAI

import { useEchoAI } from "@echoai/web/react";

function VoiceChat() {
  const {
    connect,
    disconnect,
    isConnected,
    isSpeaking,
    transcript,
    agentText,
  } = useEchoAI({
    apiUrl: "http://localhost:8000",
    token: session.access_token,
  });

  return (
    <div>
      <button onClick={isConnected ? disconnect : connect}>
        {isConnected ? "Hang Up" : "Start Call"}
      </button>
      {transcript && <p>You: {transcript}</p>}
      {agentText && <p>Agent: {agentText}</p>}
    </div>
  );
}

React Component: EchoAIButton

A drop-in button that handles connection state, microphone permissions, and visual feedback:

import { EchoAIButton } from "@echoai/web/react";

function App() {
  return (
    <EchoAIButton
      apiUrl="http://localhost:8000"
      token={session.access_token}
      assistantId="your-assistant-id"
      onTranscript={(text) => console.log("User:", text)}
      onAgentSpeak={(text) => console.log("Agent:", text)}
    />
  );
}

Props

Prop	Type	Description
`apiUrl`	`string`	HostDesk API base URL
`token`	`string`	JWT or API key for auth
`assistantId`	`string?`	Optional assistant to use
`onTranscript`	`(text: string) => void`	Called on user speech
`onAgentSpeak`	`(text: string) => void`	Called on agent speech
`className`	`string?`	CSS class for the button

Events

Event	Payload	Description
`connected`	—	WebRTC session established
`disconnected`	—	Session ended
`transcript`	`(text, isFinal)`	User speech recognized
`agentSpeaking`	`(text)`	Agent is speaking
`agentStopped`	—	Agent finished speaking
`error`	`(error)`	Connection or runtime error

Connection flow

The SDK fetches a LiveKit token from your HostDesk backend
Connects to the LiveKit room via WebRTC
The voice worker joins the room and starts the STT/LLM/TTS pipeline
Audio streams bidirectionally with low latency

Requirements

A running HostDesk backend (apps/backend)
A valid JWT session token or API key
Browser with WebRTC and microphone access