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

Event Callbacks

CallbackPayloadLocationDescription
onFirstRenderingAvatarViewFires once when the avatar renders its first frame.
onConnectionStateConnectionStateAvatarControllerFires when the WebSocket connection state changes. SDK mode only.
onConversationStateConversationStateAvatarControllerFires when the avatar’s playback state changes.
onErrorAvatarErrorAvatarControllerFires when a runtime error occurs.

ConnectionState

Indicates the current state of the WebSocket connection to the driving service.
StateDescription
disconnectedNo active connection.
connectingConnection is being established.
connectedConnection is active and ready.
failedConnection failed. On iOS and Android, includes code and message details.

ConversationState

Tracks the avatar’s current playback state.
StateDescription
idleNo active conversation — avatar shows breathing animation.
playingAvatar is actively playing audio and animation.
pausedPlayback is paused.

Usage Examples

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