JavaScript SDK / Session

Session#

A Session is what client.connect() hands back. You do not construct it. One box instance serves one live session at a time.

import { Session } from "@zeligate/zeli-avatar";

Identity and state#

getActiveSessionId(): string#

The box-issued id for this session.

isStreaming(): boolean#

Whether this session is still streaming.

Driving the avatar#

sendUserMessage(text): Promise<void>#

Sends user text through the conversational model; the avatar speaks the reply. Throws SessionError on empty text. Falls back to an HTTP POST /api/chat when the control gateway is absent, so this is the one drive method that works everywhere.

talk(text, options?): Promise<void>#

Speaks text straight through text to speech, bypassing the model and the transcript. Optional tone colours the delivery. Requires the control gateway.

A tone this box never advertised is not an error: the gateway passes any string to the voice engine, which quietly delivers the default emotion. The SDK raises a SERVER_WARNING so the mismatch is visible rather than silent.

createTalkMessageStream(options?): TalkMessageStream#

Returns a TalkMessageStream for pushing text to text to speech as it is produced. Requires the control gateway.

interruptPersona(correlationId?): Promise<void>#

Stops the avatar mid-utterance, which is barge-in. Requires the control gateway. Emits TALK_STREAM_INTERRUPTED.

Pass correlationId to stop one specific utterance. Omitted, the most recent thing this session asked to be said is stopped, which is what a caller means by stop almost every time.

Any talk stream it stops is marked before the frame goes out rather than after. The send can reject, and a caller who saw interruptPersona() throw should still see the stream reporting interrupted rather than a state claiming the utterance is fine when the avatar may well have stopped. With an explicit target, only the stream carrying that id is marked.

newConversation(): Promise<string | null>#

Close this conversation and start a fresh one, without tearing down the session. Returns the new conversation id, or null from a box old enough not to report one.

const id = await session.newConversation();
// the avatar is still on screen, still connected, and has forgotten the chat

Nothing is erased. The box keeps the conversation you just closed, so its turns stay browsable, and opens a new one beside it. That is why this is called newConversation rather than clear.

The persona and the system prompt survive. Only the turn list rotates, so the avatar keeps its character and loses its memory of what was said.

It also clears the local transcript, so client.getMessageHistory() agrees with the box rather than continuing to show a conversation the avatar has forgotten. Subscribers to MESSAGE_HISTORY_UPDATED receive the empty history.

Scoped to your credential. A box is shared, and the conversation id is never taken from the caller, so this cannot reach anybody else's history.

Talking to the avatar#

startMicrophone(options?): Promise<MicrophoneSession>#

Opens the microphone, streams what it hears to the box, and feeds the recognised words into the same conversation sendUserMessage uses. Speaking and typing are one conversation on the box, so both sides of a spoken turn land in the same transcript.

const mic = await session.startMicrophone();
 
client.on(ZeliEvent.TRANSCRIPT_PARTIAL, (t) => caption(t.text));
client.on(ZeliEvent.MESSAGE_STREAM_EVENT_RECEIVED, (c) => append(c.content));
client.on(ZeliEvent.MICROPHONE_CLOSED, (end) => {
  if (end.retired) offerToReconnect(end.reason);
});
 
await mic.setMuted(true);    // pauses, keeping the session and the permission
await mic.stop();            // releases the device and closes the socket

In a browser the audio comes from getUserMedia, so this call triggers a permission prompt. Anywhere else, pass audioCapture. The SDK converts whatever rate the device runs at to what the box reads, which is 16 kHz mono signed 16 bit little endian, and sends it as binary frames.

Resolves once the box says it is listening. A box with no microphone, a credential it will not accept, and a refusal it explains all throw here rather than arriving later as an ending. A refusal throws MicrophoneRefusedError, whose closed field carries the code, the box's sentence, and whether trying again could work.

MicrophoneSession#

session.isPaused and session.resume() are the same two on the session, and answer false when it has no microphone. session.activeMicrophone is the one this session has open, or null. Ending the session releases it, so a session that closes while somebody is still talking does not leave the microphone light on.

Media#

streamToVideoElement(target): Promise<AttachResult>#

Show this session on a <video> element. Returns { muted, reason? }.

unmute(): Promise<void>#

Restore sound after streamToVideoElement reported muted: true. Must be called from inside a user gesture handler. Throws SessionError if nothing has been attached yet.

Both are covered in detail on Media.

Correlation ids#

Every outbound utterance carries a correlation id, whether it went out as a message, a talk, or a talk stream. The id is a lowercase UUID v4, dashes included, generated by newCorrelationId() unless you supply your own.

import { newCorrelationId } from "@zeligate/zeli-avatar";
 
const id = newCorrelationId();   // "3f2a1c8e-9b4d-4e11-a7c6-2d5f80b31e94"
const talk = session.createTalkMessageStream({ correlationId: id });
// ... later, stop exactly this one
await session.interruptPersona(id);

Supplying your own is the only way the avatar's speech lines up with the rest of a distributed trace: pass a request id or a trace id minted upstream and it threads straight through to AVATAR_SPEECH_STARTED, MESSAGE_STREAM_EVENT_RECEIVED and TALK_STREAM_INTERRUPTED.

Lifecycle#

waitUntilClosed(): Promise<void>#

Resolves when the session ends, however it ends.

stopStreaming(): Promise<void>#

Ends the session and releases the box. Also wired to Symbol.asyncDispose, so await using works on a runtime that supports it.

await using session = await client.connect();
await session.talk("Hello.");
// stopStreaming() runs at scope exit

The close code names what actually ended it. See ConnectionCloseCode.

Deprecated aliases#

@zeligate/zeli-avatar is published, so a rename that broke installed code would be a worse outcome than a name that disagreed with the reference. Every name this package shipped before still works and is removed at 1.0.