Core Concepts
Conversations

Conversations

A conversation is an interactive session between a user and an avatar.

Conversation Lifecycle

  1. Start – User loads the avatar or sends first message
  2. Active – Messages are exchanged back and forth
  3. Idle – No activity (timeout after 30 minutes)
  4. End – User closes the chat or session expires

Accessing Conversations

In React

import { useConversation } from '@avatarium/react';
 
function ChatComponent() {
  const {
    messages,      // Array of all messages
    isConnected,   // WebSocket connection status
    send,          // Function to send a message
    clear          // Function to clear history
  } = useConversation();
 
  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id} className={msg.role}>
          {msg.content}
        </div>
      ))}
    </div>
  );
}

In JavaScript

const avatar = new Avatarium({ ... });
 
avatar.on('message', (message) => {
  console.log(`${message.role}: ${message.content}`);
});
 
avatar.on('conversationStart', (conversationId) => {
  console.log('Started:', conversationId);
});
 
avatar.on('conversationEnd', () => {
  console.log('Conversation ended');
});

Message Structure

Each message contains:

{
  "id": "msg_abc123",
  "role": "user" | "assistant",
  "content": "Hello, how can I help?",
  "timestamp": "2024-01-15T10:30:00Z",
  "metadata": {
    "tokens": 24,
    "latency": 187
  }
}

Conversation Context

Avatars maintain context throughout the conversation:

  • Short-term memory – Full context of current session
  • System prompt – Your personality configuration
  • User messages – Everything the user has said
  • Assistant messages – All avatar responses

Context is automatically managed to fit within AI model limits.

Saving Conversations

Enable conversation persistence:

<Avatar
  model="scarlett"
  persistConversation={true}
  conversationId="user-123-session"
/>

Retrieve past conversations via API:

GET /api/v1/conversations/{conversationId}

Conversation Events

EventTriggerData
conversationStartSession begins{ conversationId }
messageNew message{ id, role, content }
typingAvatar is thinking{ isTyping: true }
errorSomething went wrong{ error, code }
conversationEndSession ends{ reason }

Webhooks for Conversations →

AvatarsAI Providers