Documentation Index
Fetch the complete documentation index at: https://docs.liveavatar.com/llms.txt
Use this file to discover all available pages before exploring further.
LiveAvatar processes events via the LiveKit Protocol. All events follow this JSON structure:
{
"event_id": "string",
"event_type": "string",
"session_id": "string",
"source_event_id": "string | null"
}
agent-control — commands you send to the avataragent-response — events the server sends to you
Command Events
Send these to the agent-control topic.
| Event | Payload | Description |
|---|
avatar.interrupt | — | Interrupts and stops any scheduled commands. Disrupts the entire sequence of queued calls. |
avatar.speak_text | {"text": "..."} | Instructs the avatar to speak the provided text. |
avatar.speak_response | {"text": "..."} | Instructs the avatar to generate an LLM response to the input text, then speak it. |
avatar.start_listening | — | Switches the avatar to a listening state (from idle). |
avatar.stop_listening | — | Returns the avatar from listening to idle state. |
user.start_push_to_talk | — | (PTT only) Signal to start capturing user audio. |
user.stop_push_to_talk | — | (PTT only) Signal to stop capturing user audio. |
Response Events
Listen for these on the agent-response topic.
| Event | Payload | Description |
|---|
user.speak_started | — | The user has started sending audio. |
user.speak_ended | — | The user has stopped sending audio. |
avatar.speak_started | — | The avatar has started speaking. |
avatar.speak_ended | — | The avatar has finished speaking. |
user.transcription | {"text": "..."} | Transcription of the user’s speech. |
avatar.transcription | {"text": "..."} | The avatar’s text response. Emitted after LLM generation or immediately with avatar.speak_text. |
user.push_to_talk_started | — | (PTT only) PTT successfully started. |
user.push_to_talk_start_failed | — | (PTT only) PTT failed to start. |
user.push_to_talk_stopped | — | (PTT only) PTT successfully stopped. |
user.push_to_talk_stop_failed | — | (PTT only) PTT failed to stop. |
session.stopped | {"end_reason": "..."} | The session has ended. Includes the reason for termination (see below). |
session.stopped end reasons
The end_reason field on session.stopped is one of:
| Value | Meaning |
|---|
USER_DISCONNECTED | The user’s client disconnected from the session. |
USER_CLOSED | The user explicitly closed the session. |
IDLE_TIMEOUT | The session was idle for too long. |
MAX_DURATION_REACHED | The session reached its configured maximum duration. |
AGENT_HANG_UP | The agent itself terminated the call (e.g. decided the conversation was complete). Currently only emitted by the ElevenLabs agent. |
AVATAR_DELETED | The avatar used by the session was deleted. |
NO_CREDITS | The account ran out of credits. |
SERVER_ERROR | The session ended due to a server-side error. |
ZOMBIE_SESSION_REAP | The session was cleaned up after going unresponsive. |
UNKNOWN | The session ended for an unspecified reason. |
