Reference
createClient(sessionToken, options?)
Returns an AvatarGoClient for one session. Nothing happens on the network until
streamToVideoElement.
| Option | Type | Default | |
|---|---|---|---|
baseUrl | string | https://api.avatargo.ai | The API host. A trailing slash is ignored. |
timezone | string | the browser’s | The end user’s time zone, an IANA name such as "Asia/Shanghai". The character is told today’s date there, and a call still going at midnight there is told the new one. A time zone your server set when it created the session (sessionOptions.timezone) wins over this. |
client.streamToVideoElement(target, options?) → Promise<void>
Joins the session and shows the avatar. target is a <video> element or its id. The
avatar’s video goes into it; its voice plays through an audio element the SDK creates. Resolves
once joined (and the microphone is on); connection_established fires at the same moment.
The picture arrives a moment later — video_play_started says when.
| Option | Type | Default | |
|---|---|---|---|
microphone | boolean | true | Send the user’s microphone. A character listens to it; pass false for avatar only, or to join muted. |
poster | boolean | true | Show the avatar’s face in the element while the call connects: the picture the avatar is rendered from, blurred, set as the <video>’s poster and brought into focus when the video plays. A cold start can take up to half a minute; the user sees the face at once rather than a blank box. Pass false to leave the element as it is; an element that already has a poster is left alone. The picture comes from GET /v1/engine/session/face, with the session token. |
waitingPrompt | boolean or object | true | While the call waits for a free renderer, tell the user the service is busy, over the video — see Waiting for a renderer. Pass an object of your own words to change any of them, or false to draw your own from start_waiting. |
endingNotice | boolean or object | true | In the call’s last seconds, count down to its end over the top of the video — see The call’s last seconds. Pass an object of your own words, or false to draw your own from call_ending. |
In a character session the first join also starts the conversation (the character, then the avatar) — an
unused session token costs nothing. If a greeting is set on the character, the avatar says it
once it is up.
Rejects with an AvatarGoError if the session cannot be joined. If it failed
after entering the room (connection_failed, or microphone_unavailable when the microphone
could not be turned on), the SDK leaves it again, so the session ends on the server rather than
holding capacity; the rejection is the whole answer — session_ended does not fire as well.
Throws a plain Error if there is no <video> element with that id.
A client is for one session: once its session is over (you called stopStreaming() or
endSession(), or it ended), calling this again rejects with session_ended — create a new client with a new
session token.
client.endSession() → Promise<void>
Ends the session for good: tells AvatarGo and leaves as stopStreaming() does, both at once
(session_ended fires). Use it for a hang-up button: the session is over in the same moment, rather
than once the user’s absence is noticed, and a renderer still queued for it is called off. It cannot be
rejoined. It does not wait for AvatarGo’s answer: if AvatarGo cannot be reached, the client leaves all the
same and the session ends the way it does after stopStreaming(). The busy prompt’s Call later and its longest wait use it.
In an avatar-only session (your server sends the audio) your server is disconnected with it.
document.getElementById("hang-up").onclick = () => client.endSession();client.muteInputAudio() / client.unmuteInputAudio() → Promise<void>
Stops and restarts sending the microphone. The avatar keeps talking; the user is not heard while muted.
client.stopStreaming() → Promise<void>
Leaves the session. The server ends it once the user has left; until then, joining again with the
same session token rejoins it — so a page that unmounts and mounts again (React’s StrictMode
does) keeps its call. session_ended fires. To end the session for good at once, use endSession().
Called while streamToVideoElement is still joining (a cold start can take half a minute), it
cancels the join: the client never enters the room or turns the microphone on, session_ended
fires, connection_established does not, and the pending streamToVideoElement resolves. The
server notices nobody came and ends the session on its side within about 30 s.
client.sessionId — string | null
The session’s id (se_…), set once streamToVideoElement has been let into the session — the
same id your server got, for your logs or for GET /v1/sessions/{id}.
client.on(event, listener) / client.off(event, listener) → client
Add or remove a listener; both return the client, so calls chain. See Events.
client.registerToolCallHandler(toolName, handler) → () => void
Handle one of the character’s client tools; returns a function that stops handling it. See Client tools.
client.sendUserMessage(text) → Promise<void>
Type to the character: text is the user’s turn, as if they had said it. See
Typing to the character.
client.talk(text) → Promise<void>
Make the character say text as written. Off unless your server switched it on; see
Talk and add context.
client.addContext(text) → Promise<void>
Tell the character what the user is doing in your page, without a reply. Off unless your server switched it on; see Talk and add context.