Made in 10Docs
GuidesAPI
SDKs

@daxov/client

Call in the browser (microphone, voice, face, mute, end, state) and the server helpers for live events, webhooks and tool calls.

@daxov/client runs a live call in the browser from the CallStart your server got from POST /v1/calls. @daxov/client/server is for your server: the call's live events, and checking webhooks and tool calls.

Coming soonNot on npm yet

The package is private until the product has its name; @daxov/client is a placeholder name. The code below shows how it will be used.

Call, in the browser

call.ts
import { Call } from "@daxov/client";

const call = new Call();
call.on("state", (state) => render(state));
call.on("ended", (reason) => console.log("Ended:", reason));

// Straight from the person's click: browsers allow sound and the microphone only then.
button.onclick = () =>
  call.start(() => fetch("/api/calls", { method: "POST" }).then((r) => r.json()));

start does the whole start in the right order: the microphone first, then your server's CallStart, then the connection. It takes the CallStart itself, or a function that asks your server for it (called only once the microphone is open).

Options

new Call(options):

Prop

Type

Methods

MethodWhat it does
start(source)The whole start, from the click: open(), then the CallStart (source is one, or a function that returns one), then connect()
open()The sound system and the microphone. Call it straight from a click
connect(start)Connects to the call your server started and starts talking (after open()). Rejects with a CallError if the call refuses the connection
setMuted(muted)Mutes or unmutes the microphone
end(reason?)Hangs up. Safe at any time, more than once. reason goes to the logs, so a call always says why it ended
on(name, fn), once(name, fn)Listens to an event (below); returns a function that stops listening
getState(), subscribe(fn)The state, and a change listener, for your own UI framework
eventsThe live events socket when the events option opened it (the same ControlSocket your server would use), else null

State

call.getState() and the state event give one object:

FieldWhat it is
phaseidle, opening, connecting, live, ended or failed
callIdThe call's id (call_…), once connecting
maxSeconds, liveSinceThe most it can last, and when it went live (for a timer)
statusThe call's status as we report it (starting, running…)
micLevel, aiLevelLoudness from 0 to 1, for meters
aiSpeakingThe AI's voice is playing (with a face: the face is speaking)
mutedWhether the microphone is muted
errorA CallError, with a message written for the person on the call
endedReasonWhy the call ended, in plain words ("The call reached its time limit.")
playbackHow the voice is played: direct, element, loopback or face
face{ status, video, startupMs, problem }: status is off, joining, waiting, live, failed or ended; video is a MediaStream for a <video> element
transcriptLines as they come, with the events option only

Events

EventWhen
stateAnything in the state changed
phaseThe phase changed
speakingThe AI started or stopped speaking
transcriptA transcript line (with the events option)
endedThe call is over, with the reason when there is one
errorA CallError
logWhat the call is doing, for your logs (no secrets)

Errors

A CallError has a kind and a message you can show as it is:

kindWhat happened
mic_blockedThe browser or the person blocked the microphone
mic_missingThere's no microphone
mic_busyAnother app holds the microphone
unsupportedThe browser can't run a call
start_failedYour server couldn't start the call (the function given to start threw)
refusedThe call refused the connection: an expired or used ticket, or the call open elsewhere
lostThe connection dropped mid-call

Echo

The AI must not hear itself through the microphone. echo: "auto" (the default) plays the voice the way each browser's echo cancellation catches it:

echoHow the voice plays
directThrough Web Audio. Chrome and Firefox cancel this
elementThrough an <audio> element
loopbackThrough a call inside the page, which every browser treats as a call: the fix for Safari and iOS. Adds a few tens of milliseconds
autodirect on Chrome and Firefox, loopback on Safari and iOS

With a face, the voice comes from the face's own call track, which every browser cancels by itself. Headphones avoid echo whichever way.

Content-Security-Policy

A page with a Content-Security-Policy needs:

  • script-src blob:: the sound processors load from a blob: URL;
  • connect-src wss://api.daxov.com: the call's connection;
  • the face's room, when the call has a face: the livekit_url the call's ws.face names, a server of ours. The SDK joins it with the open-source LiveKit client library, which loads only when a call has a face.

@daxov/client/server, on your server

Nothing here touches a microphone or the page, so it runs in Node 22+, Deno, Bun and workers (and in browsers too).

ControlSocket: the call's live events

events.ts
import { ControlSocket } from "@daxov/client/server";

const events = new ControlSocket(start.events_url);
events.on("transcript", (line) => console.log(line.who, line.text));
events.on("ended", (e) => console.log(e.reason, e.message));

const snapshot = await events.connect();
if (snapshot.controls.includes("say")) await events.say("Your order has shipped.");

It speaks the live events socket for you: the snapshot, each transcript line once (also across reconnects), and your controls answered by their ack.

MemberWhat it does
connect()Connects and resolves with the first snapshot. Fails if that first connection is refused; later drops are reconnected with the same token
say(text)The character says this next, word for word (at most 1,000 characters). Resolves when the call takes it
context(text)A note the mind reads at the head of its next turn and keeps (at most 4,000 characters; 20,000 a call)
end()Ends the call, as POST /v1/calls/{id}/end does
close()Stops listening. The call goes on
snapshot, status, transcript, controls, endedWhat it last heard

Events: snapshot, status, transcript, speaking, tool, lagged, ended, error, close (with final when it won't reconnect), reconnecting, and message for every frame.

Options: WebSocket (a WebSocket class, where there's no global one, for example the ws package's), reconnect (default true), retryDelaysMs, and ackTimeoutMs (default 10,000). A refused control rejects with a ControlError whose code is the socket's (not_supported, queue_full, too_long…).

Webhooks and tool calls

webhooks.ts
import { readWebhook, WebhookVerificationError } from "@daxov/client/server";

try {
  const event = await readWebhook(process.env.WEBHOOK_SECRET, req.headers, rawBody);
  // dedupe on event.id: deliveries are at least once, in no guaranteed order
} catch (e) {
  if (e instanceof WebhookVerificationError) return reply(400);
  throw e;
}
FunctionWhat it does
readWebhook(secret, headers, rawBody)Checks a webhook delivery and returns its event, typed. Throws WebhookVerificationError when it isn't ours
readToolCall(secret, headers, rawBody)The same for a tool call, with the tool's secret: returns what the character asked for
verifyWebhook(secret, headers, rawBody)true when a signature matches and the timestamp is recent
signWebhook(secret, id, timestamp, rawBody)Signs a body as we do, for your tests

headers may be a Headers or Node's headers object; rawBody is the body exactly as it arrived (a string or bytes). The timestamp may be at most 300 seconds off (toleranceSeconds changes it). They use WebCrypto. See Verify signatures.

forBrowser(start)

Takes events_url out of a CallStart before it goes to the person's browser. Whoever holds that token can make the character say anything and end the call, so it stays on your server.

Types

The API's shapes, for TypeScript: CallStart, BrowserCallStart, ApiCall, CallDetail, CallAnalysis, WebhookEvent, ToolCallRequest, TranscriptTurn, ApiErrorBody and more.

On this page