> ## Documentation Index
> Fetch the complete documentation index at: https://spatialwalk-6179c111.mintlify.site/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

**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);
};
```

**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)")
}
```

**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}")
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.