LiveAvatar Session Life Cycle

A LiveAvatar Session represents a real-time, two-way interaction between a user and an AI avatar. From a developer’s perspective, a session behaves like a live room that you can join, stream data into, and listen for key events as the conversation unfolds.

While every session may look different depending on your integration, they all follow a similar lifecycle.

1. Starting a Session and connecting to the LiveKit room

To begin, configure the session by specifying the desired avatar, voice, and context, then create the session via our API. In response, you’ll receive connection details that allow both your user and the avatar to join the same LiveKit room.

Once connected to the room via WebRTC, the session becomes active — enabling real-time exchange of audio, video, and text data between the user and the avatar.

At this point, the conversation environment is fully live and ready for interaction.

2. Managing the Session

Full Mode

After both the user and the avatar have joined the room, they can begin interacting in real time. From this point forward, the session is driven by a combination of client-side and server-side events that coordinate communication.

• Command / Client-side events allow developers to send signals or issue commands to the avatar — for example, instructing it to speak a certain phrase, or handle an interrupt while it's speaking.
• Server-side events are emitted by the session to report what’s happening — such as when the avatar starts or stops speaking or when the connection state changes.

By listening to these events, you can build responsive, adaptive experiences — updating your UI in real time, triggering custom animations, or handling interruptions gracefully.

In essence, client-side and server-side events form the backbone of the conversational loop: your app sends signals to the avatar, and the session broadcasts updates so your interface stays in sync.

See the event list to see the up to date supported events.

Custom Mode

In Custom Mode, we will no longer emit events on the state of the application. We assume that you have pre-existing full control and instead we offer is a way to pass in input audio via an websocket connection. We then output video frame data via the livekit room.

3. Ending the Session

When the interaction is complete, the session is closed. In most cases, this happens when the client ends the connection after the user finishes the conversation.

The server may also terminate a session under certain conditions, including (but not limited to):

• No user detected in the room
• Insufficient credits or quota remaining for streaming

When a session ends, both the user and the avatar are disconnected from the room, and all active media streams are stopped. You can use this moment to clean up resources, show a summary screen, or prompt the user to start a new session.