Events

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"
}

Events are differentiated by LiveKit room topic:

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.

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).

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.