Skip to main content
The ElevenLabs Agent Connector bridges ElevenLabs Agents with 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 connector: 
{
  "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)
  • LiveAvatar dispatches a worker that handles interaction with your ElevenLabs Agent
  • Agent audio drives avatar animation in real time
The ElevenLabs Agent Connector uses the FULL Mode event system, not standard LITE Mode events. The WebSocket command events described in the LITE Mode Events page do not apply here. See the Events section below for details.

​
Events

The ElevenLabs Agent Connector 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