Skip to main content
This integration is currently in beta.
The ElevenLabs Agent Plugin creates a seamless bridge between ElevenLabs Agents and LiveAvatar. ElevenLabs handles the conversational AI while LiveAvatar renders the avatar video.

​
Requirements

  • ElevenLabs API key with permissions: convai_read, user_read, voices_read
  • ElevenLabs Agent ID
  • Audio output configured as PCM 24K

​
Setup

1. Register your ElevenLabs API key: 
curl -X POST https://api.liveavatar.com/v1/secrets \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "secret_type": "ELEVENLABS_API_KEY",
    "secret_value": "<elevenlabs_api_key>",
    "secret_name": "ElevenLabs Agent Key"
  }'
2. Start a session with the plugin: 
{
  "mode": "LITE",
  "avatar_id": "<avatar_id>",
  "elevenlabs_agent_config": {
    "secret_id": "<secret_id>",
    "agent_id": "<elevenlabs_agent_id>"
  }
}

​
How it works

  • A LiveKit room is automatically created (no WebSocket endpoint returned)
  • Standard LITE events are not available — uses FULL Mode event system instead
  • LiveAvatar dispatches a worker that handles interaction with your ElevenLabs Agent
  • Agent audio drives avatar animation in real time

​
Events

The ElevenLabs Agent Plugin emits standard FULL Mode response events such as user.speak_started, avatar.transcription, etc. In addition, underlying ElevenLabs server events are forwarded via a dedicated event type:
EventPayloadDescription
elevenlabs_agent_event{"elevenlabs_event_type": "...", "data": {...}}A passthrough of raw server events from the ElevenLabs Conversational AI agent.
The elevenlabs_event_type field contains the original ElevenLabs event type string, and data contains the full event payload from ElevenLabs. This lets you react to any ElevenLabs-specific behavior (e.g. tool calls, agent state changes) that isn’t covered by the standard LiveAvatar events.

​
Listening for ElevenLabs events

import { AgentEventsEnum } from "@heygen/liveavatar-web-sdk";

session.on(AgentEventsEnum.ELEVENLABS_AGENT_EVENT, (event) => {
  console.log("ElevenLabs event:", event.elevenlabs_event_type, event.data);
});
For a full list of possible ElevenLabs event types, see the ElevenLabs Conversational AI documentation.

​
Billing

  • LiveAvatar: 1 credit per session minute (avatar video only)
  • ElevenLabs: charges separately for agent usage