Events

The SDK emits events for various avatar states and actions.

Event Types

Event	Payload	Description
`connected`	`{ conversationId: string }`	Connection established
`disconnected`	`{ reason: string }`	Connection closed
`message`	`Message`	Message sent or received
`message:user`	`Message`	User message sent
`message:assistant`	`Message`	Assistant message received
`speak:start`	`{ text: string }`	Avatar started speaking
`speak:end`	`{ duration: number }`	Avatar finished speaking
`error`	`Error`	Error occurred
`status:change`	`{ from: Status, to: Status }`	Status changed

Using with React

Component Props

<Avatar
  apiKey="..."
  avatarId="aria-001"
  onConnected={() => console.log('Connected')}
  onMessage={(msg) => console.log(msg)}
  onError={(err) => console.error(err)}
/>

With useAvatar Hook

import { useEffect } from 'react';
import { useAvatar, useAvatarEvents } from '@avatarium/react';
 
function App() {
  const events = useAvatarEvents();
 
  useEffect(() => {
    const unsubscribe = events.on('message:assistant', (msg) => {
      console.log('Avatar said:', msg.content);
    });
 
    return unsubscribe;
  }, [events]);
 
  return <Avatar apiKey="..." avatarId="aria-001" />;
}

Using with Core SDK

import { Avatarium } from '@avatarium/sdk';
 
const avatar = new Avatarium({
  apiKey: 'av_live_xxxxx',
  container: '#avatar',
  avatarId: 'aria-001',
});
 
// Subscribe to events
avatar.on('connected', ({ conversationId }) => {
  console.log('Connected:', conversationId);
});
 
avatar.on('message:assistant', (message) => {
  console.log('Avatar:', message.content);
});
 
avatar.on('speak:start', ({ text }) => {
  console.log('Speaking:', text);
});
 
avatar.on('error', (error) => {
  console.error('Error:', error);
});
 
// Unsubscribe
const unsubscribe = avatar.on('message', (msg) => {
  // ...
});
unsubscribe(); // Remove listener

Event Payloads

Message

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: Date;
  audioUrl?: string;
  usage?: {
    aiTokens: number;
    ttsCharacters: number;
  };
}

Error

interface AvatarError extends Error {
  code: string;
  statusCode?: number;
  details?: Record<string, unknown>;
}

Error codes:

CONNECTION_FAILED - Could not establish connection
AUTH_FAILED - Invalid API key
RATE_LIMITED - Rate limit exceeded
PROVIDER_ERROR - AI/TTS provider error
NETWORK_ERROR - Network connectivity issue

Hooks Overview