> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatialreal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Available events to handle in your application, and how to handle them.

AvatarKit client SDKs expose event callbacks so your app can react to connection changes, conversation state transitions, and errors in real time.

## Event Callbacks

| Callback              | Payload             | Location           | Description                                                       |
| --------------------- | ------------------- | ------------------ | ----------------------------------------------------------------- |
| `onFirstRendering`    | —                   | `AvatarView`       | Fires once when the avatar renders its first frame.               |
| `onConnectionState`   | `ConnectionState`   | `AvatarController` | Fires when the WebSocket connection state changes. SDK mode only. |
| `onConversationState` | `ConversationState` | `AvatarController` | Fires when the avatar's playback state changes.                   |
| `onError`             | `AvatarError`       | `AvatarController` | Fires when a runtime error occurs.                                |

## ConnectionState

Indicates the current state of the WebSocket connection to the driving service.

| State          | Description                                                                   |
| -------------- | ----------------------------------------------------------------------------- |
| `disconnected` | No active connection.                                                         |
| `connecting`   | Connection is being established.                                              |
| `connected`    | Connection is active and ready.                                               |
| `failed`       | Connection failed. On iOS and Android, includes `code` and `message` details. |

## ConversationState

Tracks the avatar's current playback state.

| State     | Description                                                |
| --------- | ---------------------------------------------------------- |
| `idle`    | No active conversation — avatar shows breathing animation. |
| `playing` | Avatar is actively playing audio and animation.            |
| `paused`  | Playback is paused.                                        |

## Usage Examples

<Tabs>
  <Tab title="Web">
    ```typescript theme={null}
    const controller = avatarView.controller;

    // First frame rendered
    avatarView.onFirstRendering = () => {
      console.log('First frame rendered');
    };

    // Connection state (SDK mode only)
    controller.onConnectionState = (state) => {
      console.log('Connection:', state);
    };

    // Conversation state
    controller.onConversationState = (state) => {
      console.log('Conversation:', state);
    };

    // Error handling
    controller.onError = (error) => {
      console.error('Error:', error.code, error.message);
    };
    ```
  </Tab>

  <Tab title="iOS">
    ```swift theme={null}
    let controller = avatarView.controller

    // First frame rendered
    avatarView.onFirstRendering = {
        print("First frame rendered")
    }

    // Connection state (SDK mode only)
    controller.onConnectionState = { state in
        switch state {
        case .connected:
            print("Connected")
        case .failed(let code, let message):
            print("Failed: \(code) \(message)")
        default:
            break
        }
    }

    // Conversation state
    controller.onConversationState = { state in
        print("Conversation: \(state)")
    }

    // Error handling
    controller.onError = { error in
        print("Error: \(error.localizedDescription)")
    }
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin theme={null}
    val controller = avatarView.controller

    // First frame rendered
    avatarView.onFirstRendering = {
        Log.d("Avatar", "First frame rendered")
    }

    // Connection state (SDK mode only)
    controller?.onConnectionState = { state ->
        when (state) {
            is ConnectionState.Connected ->
                Log.d("Avatar", "Connected")
            is ConnectionState.Failed ->
                Log.e("Avatar", "Failed: ${state.message}")
            else -> {}
        }
    }

    // Conversation state
    controller?.onConversationState = { state ->
        Log.d("Avatar", "Conversation: $state")
    }

    // Error handling
    controller?.onError = { error ->
        Log.e("Avatar", "Error: ${error.message}")
    }
    ```
  </Tab>
</Tabs>