Skip to main content
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:
  • agent-control — commands you send to the avatar
  • agent-response — events the server sends to you

​
Command Events

Send these to the agent-control topic.
EventPayloadDescription
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.
EventPayloadDescription
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.