Client State & Events

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.

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

Detailed definitions for each platform: Web ConversationState | iOS ConversationState | Android ConversationState | Flutter ConversationState

`ConnectionState`

Only available in Direct Mode. 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.

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 | iOS ConnectionState | Android ConnectionState | Flutter ConnectionState

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.

Start Here

Quickstarts

Platform Integrations

Standalone Integrations

Concepts

Examples & Support

Client State & Events

`ConversationState`

`ConnectionState`

Errors (`onError`)

​ConversationState

​ConnectionState

​Errors (onError)

`ConversationState`

`ConnectionState`

Errors (`onError`)