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

# Client State & Events

> AvatarKit client state callbacks, including ConversationState, ConnectionState, error events, and recovery context.

`AvatarController` exposes two independent state enums that you can observe through callbacks.

## `ConversationState`

The current playback state of the digital human.

| State     | Meaning                                                             |
| --------- | ------------------------------------------------------------------- |
| `idle`    | Plays idle animation, the breathing state, with no active response. |
| `playing` | Plays audio and speaking animation.                                 |
| `paused`  | Audio and visuals are paused, with state and buffers kept.          |

Subscribe to state changes through `AvatarController.onConversationState`.

<Note>
  Android also has an intermediate `Active` state. It means avatar speech audio has been received, but playable motion data is not ready yet.
</Note>

Detailed definitions for each platform: [Web `ConversationState`](/sdk-reference/web-sdk/reference#conversationstate) | [iOS `ConversationState`](/sdk-reference/ios-sdk/api-reference#conversationstate) | [Android `ConversationState`](/sdk-reference/android-sdk/api-reference#conversationstate) | [Flutter `ConversationState`](/sdk-reference/flutter-sdk/api-reference#render-and-control-playback)

## `ConnectionState`

<Note>
  **Only available in [Direct Mode](/direct-mode/overview)**. In Platform Integrations and Backend Mode integrations, the connection is managed by the agent worker, TEN graph, or developer backend, and is not exposed through `AvatarController.ConnectionState`.
</Note>

The WebSocket connection state from AvatarKit to Motion Server in Direct Mode integrations.

| State          | Meaning                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------- |
| `disconnected` | No active connection.                                                                     |
| `connecting`   | Handshake in progress.                                                                    |
| `connected`    | Connection is active and can receive avatar speech audio.                                 |
| `failed`       | Connection failed. On iOS, Android, and Flutter SDKs, it carries additional error detail. |

Subscribe to state changes through `AvatarController.onConnectionState`.

Detailed definitions for each platform: [Web `ConnectionState`](/sdk-reference/web-sdk/reference#connectionstate) | [iOS `ConnectionState`](/sdk-reference/ios-sdk/api-reference#connectionstate) | [Android `ConnectionState`](/sdk-reference/android-sdk/api-reference#connectionstate) | [Flutter `ConnectionState`](/sdk-reference/flutter-sdk/api-reference#render-and-control-playback)

## Errors (`onError`)

Subscribe through `AvatarController.onError`. Errors are grouped by category:

| Category             | Representative errors                                                                                               | Mode availability                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Authentication**   | `sessionTokenExpired`, `sessionTokenInvalid`, `appIDUnrecognized`, `insufficientBalance`, `concurrentLimitExceeded` | Direct Mode only. Other integrations handle these on the backend or plugin side. |
| **Resource loading** | `avatarIDUnrecognized`, `avatarAssetsMissing`, `failedToFetchAvatarMetadata`                                        | All integrations.                                                                |
| **Connection**       | `websocketError`, `websocketClosedAbnormally`, `sessionTimeout`                                                     | Direct Mode only.                                                                |
| **Server**           | `serverError`                                                                                                       | All integrations.                                                                |

Complete error enum, including WebSocket close codes: [Resources -> Error Codes](/resources/server-error).