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

# Events

> Events for managing FULL Mode sessions

LiveAvatar processes events via the LiveKit Protocol. All events follow this JSON structure:

```json theme={null}
{
  "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.

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