JavaScript SDK / Events & models

Events and models#

Register handlers on the client, not the session, so they are in place before connect() opens anything. Handler arguments are typed per event through ZeliEventMap.

import { ZeliEvent, type ZeliEventMap } from "@zeligate/zeli-avatar";

ZeliEvent#

The five typed avatar events above come from the control socket. This SDK has no LiveKit client, so a session you joined by LiveKit does not fire them here. The box publishes the same frames (all but user.transcription) on the room's text stream topic zeli.avatar_events; read that topic with livekit-client (one JSON object per stream, the type field names the event). The Python SDK's zeli.livekit.AvatarSession subscribes for you.

From the microphone#

These arrive only while session.startMicrophone() is running. The reply to something spoken is not among them, deliberately: it arrives on MESSAGE_STREAM_EVENT_RECEIVED and MESSAGE_RECEIVED above, exactly as a typed turn does, so one renderer serves both.

From your custom tools#

These four arrive whichever socket the call came in on, the control socket or the microphone socket, so a page draws one lifecycle. Answer a call with client.registerToolCallHandler(name, handler); the events are for showing what is happening. The full contract, the failure reasons and a worked example are under Tools.

Models#

SessionInfo#

Carried by SESSION_READY.

Message#

A complete message in the transcript.

MessageStreamEvent#

An incremental chunk of an assistant reply.

EmotionEvent#

SessionExpiredEvent#

Why the avatar server retired a session. Two clocks can end one and reason names which.

UnknownFrameEvent#

A control frame this SDK has no branch for. It is still ignored, so a newer avatar server cannot break an older client; what this adds is that ignoring it is visible.

MicrophoneReady#

Carried by MICROPHONE_READY, and the only proof the microphone session works.

TranscriptPartial and TranscriptFinal#

TurnEndpoint#

MicrophoneState#

ToolInvocation and ReplyMetric#

MicrophoneClosed#

Carried by MICROPHONE_CLOSED, and by MicrophoneRefusedError.closed when the avatar server refuses at the start.

MicrophoneCloseCode#

ConnectionCloseCode#

The first argument of CONNECTION_CLOSED. These are four situations a caller reacts to differently, which is why they are not lumped together.

MessageRole#

user, assistant, system.

Other exported enums#

These describe the wire and are exported so a caller can name what it sees in a log, rather than because a typical app reaches for them.

Example#

import { ZeliClient, ZeliEvent, MessageRole } from "@zeligate/zeli-avatar";
 
const client = new ZeliClient({ serverUrl, sessionToken });
 
client.addListener(ZeliEvent.SESSION_READY, (info) => {
  console.log("tones on this avatar:", info.tones.join(", "));
});
 
client.addListener(ZeliEvent.MESSAGE_STREAM_EVENT_RECEIVED, (chunk) => {
  process.stdout.write(chunk.content);
  if (chunk.endOfSpeech) process.stdout.write("\n");
});
 
client.addListener(ZeliEvent.MESSAGE_HISTORY_UPDATED, (history) => {
  const spoken = history.filter((m) => m.role === MessageRole.ASSISTANT);
  render(spoken);
});
 
client.addListener(ZeliEvent.CONNECTION_CLOSED, (code, reason) => {
  console.log("closed:", code, reason ?? "");
});