Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.liveavatar.com/llms.txt

Use this file to discover all available pages before exploring further.

Agora’s Conversational AI Engine ships LiveAvatar as a first-class avatar provider. You keep Agora’s voice orchestration (ASR, LLM, TTS) and Agora SD-RTN transport — LiveAvatar adds the avatar video participant inside the same channel.
This page assumes you already have an Agora project with Conversational AI enabled and can start a voice agent against an Agora RTC channel. If you do not, a different integration path will likely fit better — head back to Integration paths to pick one.
Upstream reference: Agora docs — LiveAvatar by HeyGen.

​
Prerequisites

  • A LiveAvatar account and API key. Sign up at app.liveavatar.com.
  • An Agora project with Conversational AI Engine enabled, plus an App ID and Basic Auth credentials for the REST API.
  • A way to mint Agora RTC tokens for at least three participants: the end user, the Agora agent, and the LiveAvatar avatar. The agent and avatar tokens need publish permission; the user token needs both publish (microphone) and subscribe.

​
Installation

There is no SDK to install on your side. The integration is server-driven: you call Agora’s join REST endpoint with an avatar block, and Agora’s backend brings LiveAvatar into your channel.

​
Configuration

LiveAvatar is selected by adding an avatar block under properties in the Agora join request body: 
{
  "avatar": {
    "vendor": "liveavatar",
    "enable": true,
    "params": {
      "api_key": "<liveavatar_api_key>",
      "avatar_id": "<liveavatar_avatar_id>",
      "quality": "high",
      "agora_uid": "<avatar_rtc_uid>",
      "agora_token": "<avatar_rtc_token>"
    }
  }
}
ParameterRequiredNotes
api_keyyesYour LiveAvatar key from app.liveavatar.com.
avatar_idyesThe avatar to render.
qualityyeshigh (720p), medium (480p), or low (360p).
agora_uidyesRTC UID the avatar publishes under. Must be distinct from your agent_rtc_uid and any remote_rtc_uids.
agora_tokenyesRTC token minted for agora_uid on the same channel as the agent, with publish permission.
activity_idle_timeoutnoSeconds of silence before the avatar tears down. Default 120.
disable_idle_timeoutnoDefault false. Set true to keep the avatar alive indefinitely; overrides activity_idle_timeout.
TTS must be 24 kHz. LiveAvatar consumes audio at a 24,000 Hz sample rate. Any other rate in the tts block will error at session start.

​
How Agora + LiveAvatar fit together

An Agora RTC channel hosts the conversation between three participants:
ParticipantPublishesSubscribes to
End userMicrophone audioAvatar audio + video
Agora agent (agent_rtc_uid)(no media; forwards TTS audio to LiveAvatar)User microphone
LiveAvatar (agora_uid)Lip-synced audio + videoTTS audio forwarded by Agora
The avatar is its own RTC publisher. Agora’s Conversational AI Engine routes synthesized TTS audio to LiveAvatar, which lip-syncs and publishes audio + video back into the channel under agora_uid. Your frontend subscribes to that UID for the avatar’s tracks.

​
How the session starts up

  1. You mint tokens. Issue Agora RTC tokens for the agent UID and the avatar UID against the channel your end user will join.
  2. You POST /join. Call https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join with properties.avatar set to the LiveAvatar block above, alongside your llm, asr, and tts configuration. The response returns an agent_id — store it; you will need it to stop the session.
  3. Agora starts the agent. The Conversational AI Engine joins the channel as agent_rtc_uid and starts its ASR → LLM → TTS loop.
  4. Agora spawns LiveAvatar. Using your api_key, avatar_id, agora_uid, and agora_token, Agora’s backend opens a LiveAvatar session and the avatar joins the channel as a publisher.
  5. Your frontend subscribes. The end user joins the channel, subscribes to the avatar’s audio + video tracks, and the conversation runs.

​
Stopping the session

POST to https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agent_id/leave with the same Authorization: Basic header used for /join, where :agent_id is the value returned from /join. Agora tears down the agent and the LiveAvatar session together.

​
Minimal example

ElevenLabs TTS at 24 kHz, pointed at LiveAvatar: 
curl --request POST \
  --url "https://api.agora.io/api/conversational-ai-agent/v2/projects/$AGORA_APP_ID/join" \
  --header "Authorization: Basic $AGORA_BASIC_AUTH" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "liveavatar-session-1",
    "properties": {
      "channel": "demo-room",
      "token": "<agent_rtc_token>",
      "agent_rtc_uid": "1000",
      "remote_rtc_uids": ["2000"],
      "idle_timeout": 120,
      "asr": { "language": "en-US" },
      "llm": {
        "url": "https://api.openai.com/v1/chat/completions",
        "api_key": "<openai_key>",
        "system_messages": [
          { "role": "system", "content": "You are a helpful avatar." }
        ]
      },
      "tts": {
        "vendor": "elevenlabs",
        "params": {
          "base_url": "wss://api.elevenlabs.io/v1",
          "key": "<elevenlabs_key>",
          "model_id": "eleven_flash_v2_5",
          "voice_id": "pNInz6obpgDQGcFmaJgB",
          "sample_rate": 24000
        }
      },
      "avatar": {
        "vendor": "liveavatar",
        "enable": true,
        "params": {
          "api_key": "<liveavatar_api_key>",
          "avatar_id": "<liveavatar_avatar_id>",
          "quality": "high",
          "agora_uid": "3000",
          "agora_token": "<avatar_rtc_token>"
        }
      }
    }
  }'
agent_rtc_uid, the user UID in remote_rtc_uids, and avatar.params.agora_uid must all be different. Mint a separate token for each.

​
What changes versus a voice-only Agora agent

ConcernVoice-only Agora agentWith LiveAvatar
Channel participantsUser + agentUser + agent + avatar
Where TTS audio surfacesPublished by the agentForwarded to LiveAvatar; avatar publishes audio + video
Tokens to mintAgent + userAgent + user + avatar
TTS sample rateVendor defaultLocked to 24 kHz
Frontend renderingAudio-only subscribeMust also subscribe to the avatar UID’s video track
BillingAgora minutes + your inferenceAgora minutes + your inference + LiveAvatar minutes

​
Concurrency and limits

Concurrent sessions are capped by the lower of your Agora Conversational AI limit and your LiveAvatar plan limit. Provision both sides before scaling load tests.

​
Resources

Agora — LiveAvatar by HeyGen

Upstream Agora reference for the LiveAvatar avatar provider.

Agora Conversational AI Engine

Product overview of the Agora pipeline LiveAvatar plugs into.