Conversations

Manage conversation sessions with AI avatars.

Create Conversation

POST /v1/conversations

Creates a new conversation session. Returns a WebSocket URL for real-time interaction.

Request Body

Parameter	Type	Required	Description
`avatarId`	string	No	Avatar identifier
`provider`	string	No	AI provider: `groq`, `openai`, `gemini`, `anthropic`
`systemPrompt`	string	No	Custom system prompt
`byokAI`	object	No	BYOK configuration for using your own AI key

BYOK Configuration

Parameter	Type	Required	Description
`byokAI.provider`	string	Yes	`groq`, `openai`, `anthropic`, `gemini`
`byokAI.apiKey`	string	Yes	Your AI provider API key
`byokAI.model`	string	No	Specific model to use
`byokAI.baseUrl`	string	No	Custom API base URL

Example Request

curl -X POST https://api.avatarium.ai/v1/conversations \
  -H "Authorization: Bearer av_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "avatarId": "aria-001",
    "provider": "groq",
    "systemPrompt": "You are a helpful assistant named Aria."
  }'

Example Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "avatarId": "aria-001",
    "wsUrl": "wss://api.avatarium.ai/v1/conversations/550e8400.../ws",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "byokEnabled": false
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Get Conversation

GET /v1/conversations/:id

Retrieves a conversation and its messages.

Path Parameters

Parameter	Type	Description
`id`	string	Conversation ID

Example Request

curl https://api.avatarium.ai/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer av_live_xxxxx"

Example Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Hello!",
        "createdAt": "2025-01-15T10:01:00.000Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "Hi there! How can I help you today?",
        "createdAt": "2025-01-15T10:01:01.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

End Conversation

POST /v1/conversations/:id/end

Ends a conversation session and closes all WebSocket connections.

Example Request

curl -X POST https://api.avatarium.ai/v1/conversations/550e8400.../end \
  -H "Authorization: Bearer av_live_xxxxx"

Example Response

{
  "data": {
    "success": true
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

WebSocket Connection

GET /v1/conversations/:id/ws

Upgrade to a WebSocket for real-time conversation. The wsUrl from the create response can be used directly.

Client → Server Messages

{
  "type": "message",
  "content": "Hello, how are you?"
}

{
  "type": "ping"
}

Server → Client Messages

Type	Description
`message`	New message (user or assistant)
`stream_start`	AI response streaming begins
`stream_chunk`	Text chunk of streaming response
`stream_end`	Streaming complete, includes final message
`pong`	Response to ping
`error`	Error occurred

Example WebSocket Flow

const ws = new WebSocket(wsUrl);
 
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
 
  switch (data.type) {
    case 'stream_start':
      console.log('AI is responding...');
      break;
    case 'stream_chunk':
      console.log('Chunk:', data.data);
      break;
    case 'stream_end':
      console.log('Full response:', data.data.content);
      break;
    case 'message':
      console.log('Message:', data.data);
      break;
  }
};
 
// Send a message
ws.send(JSON.stringify({
  type: 'message',
  content: 'Tell me about Avatarium'
}));

Authentication Messages