Events

The Avatarium embed communicates with your page via postMessage. The SDK and React packages wrap these into typed event callbacks.

`AvatariumEmbed` event props (React)

Prop	Payload	Description
`onReady`	`{ avatar: string; thumbnail?: string }`	Avatar loaded and widget is ready
`onStateChange`	`state: string`	State changed – one of `IDLE`, `LISTENING`, `RECORDING`, `PROCESSING`, `SPEAKING`
`onSpeakStart`	–	Avatar started speaking
`onSpeakEnd`	–	Avatar finished speaking
`onTranscript`	`text: string`	User speech transcribed
`onError`	`error: string`	Error occurred inside the widget

Example

import { AvatariumEmbed } from '@avatarium/react';
 
function App() {
  return (
    <AvatariumEmbed
      shortId="YOUR_SHORT_ID"
      mode="voice"
      onReady={(data) => console.log('Ready:', data.avatar)}
      onStateChange={(state) => console.log('State:', state)}
      onSpeakStart={() => console.log('Speaking…')}
      onSpeakEnd={() => console.log('Done')}
      onTranscript={(text) => console.log('User said:', text)}
      onError={(err) => console.error('Error:', err)}
      style={{ width: 400, height: 600 }}
    />
  );
}

Core SDK events (`@avatarium/js`)

import { Avatarium } from '@avatarium/js';
 
const avatar = new Avatarium(document.getElementById('avatar')!, {
  shortId: 'YOUR_SHORT_ID',
  mode: 'voice',
});
 
// Fired when the widget finishes loading
avatar.on('ready', (data) => {
  console.log('Avatar name:', data.avatar);
});
 
// Fired whenever widget state changes
avatar.on('state', ({ state }) => {
  console.log('State:', state); // IDLE | LISTENING | PROCESSING | SPEAKING
});
 
// Fired when TTS provider changes inside the widget
avatar.on('ttsConfigChanged', ({ provider }) => {
  console.log('TTS provider:', provider);
});

Imperative commands (React `ref`)

Use a ref to control the avatar programmatically:

import { useRef } from 'react';
import { AvatariumEmbed, type AvatariumEmbedHandle } from '@avatarium/react';
 
function App() {
  const avatarRef = useRef<AvatariumEmbedHandle>(null);
 
  return (
    <>
      <AvatariumEmbed
        ref={avatarRef}
        shortId="YOUR_SHORT_ID"
        style={{ width: 400, height: 600 }}
      />
      <button onClick={() => avatarRef.current?.speak('Hello, world!')}>
        Speak
      </button>
      <button onClick={() => avatarRef.current?.stopSpeaking()}>Stop</button>
    </>
  );
}

Available handle methods

Method	Description
`speak(text, options?)`	Make the avatar say text (`options.mood`, `options.speed`)
`stopSpeaking()`	Interrupt current speech
`startVoice()`	Start microphone / voice mode
`stopVoice()`	Stop microphone
`setMood(mood)`	Set avatar mood (`neutral`, `happy`, `sad`, …)
`setVolume(volume)`	Set volume 0–1
`resumeAudio()`	Resume AudioContext after a user gesture

Listening for postMessage directly (no SDK)

If you embed via a plain <iframe>, listen for window.message:

window.addEventListener('message', (event) => {
  const { source, event: evt, state, text } = event.data ?? {};
 
  // Widget sends: source = 'avatarium' (chat) or 'avatarium-voice' (voice)
  if (source !== 'avatarium' && source !== 'avatarium-voice') return;
 
  if (evt === 'ready')         console.log('Ready');
  if (evt === 'stateChanged')  console.log('State:', state);
  if (evt === 'speakStart')    console.log('Speaking');
  if (evt === 'speakEnd')      console.log('Done');
  if (evt === 'transcript')    console.log('User said:', text);
  if (evt === 'error')         console.error('Error');
});

Error codes

Code	Meaning
`CONNECTION_FAILED`	Could not load the avatar widget
`AUTH_FAILED`	Short ID not found or avatar is private
`RATE_LIMITED`	Too many requests
`PROVIDER_ERROR`	AI or TTS provider returned an error
`NETWORK_ERROR`	Network connectivity issue

Hooks Windows (Coming Soon)