// Troubleshoot and debug LiveAvatar integration issues. Use when the user's LiveAvatar integration isn't working, the avatar is silent, audio is garbled, sessions fail to start, events aren't received, or they're getting API errors.
Collect and submit developer feedback to the LiveAvatar team. Use when: (1) A LiveAvatar integration is done, working, finished, or complete, (2) The user says "it works", "we're done", "that's it", "ship it", (3) The user is frustrated, stuck, or giving up — "this is broken", "this doesn't work", "I'm stuck", "I give up", "this is frustrating", "I want to report an issue", (4) The user explicitly asks to give feedback, report a bug, file an issue, or share a suggestion about LiveAvatar, (5) You've seen 3+ failed attempts at the same integration step, (6) You just finished writing or generating LiveAvatar integration code for the user.
Build a LiveAvatar integration end-to-end — assesses the user's existing stack, recommends the optimal path, and guides implementation. Use when: (1) Building a new LiveAvatar integration, (2) Adding a real-time avatar to an app or site, (3) Connecting LiveAvatar to an existing AI pipeline, (4) User mentions LiveAvatar, real-time avatar, interactive avatar, conversational avatar, or lip-sync avatar, (5) Deciding between Embed, FULL Mode, and LITE Mode, (6) Migrating from HeyGen Interactive Avatar to LiveAvatar.
| name | liveavatar-debug |
| description | Troubleshoot and debug LiveAvatar integration issues. Use when the user's LiveAvatar integration isn't working, the avatar is silent, audio is garbled, sessions fail to start, events aren't received, or they're getting API errors. |
| license | MIT |
| metadata | {"author":"heygen","version":"1.0.0"} |
Symptom-based troubleshooting for LiveAvatar integrations. Find your symptom below and follow the fix.
Most likely: Missing context_id in FULL Mode.
Without a context_id, the avatar enters restricted mode — streams video but ignores user input. No error thrown.
Fix: Create a context via POST /v1/contexts with at least a prompt field. Include the returned context_id in your session token's avatar_persona.
Other causes:
allow="microphone" on iframe)Most likely: Wrong audio format.
Required: PCM 16-bit signed, 24KHz, base64. No error returned for wrong format.
Checklist:
Quick test: Send a known-good 440Hz test tone. If it works but your TTS doesn't, resample your TTS output.
Most likely: Wrong auth header.
| Endpoint | Correct auth |
|---|---|
POST /v1/sessions/token | X-API-KEY: <api_key> |
POST /v1/sessions/start | Authorization: Bearer <session_token> |
Common mistakes: using API key on /start, using Bearer token on /token, putting API key in Bearer format.
agent-control, receive from agent-responseevent_type, event_id, session_idMost likely: Sending before connected.
Wait for {"type": "session.state_updated", "state": "connected"} before sending any commands.
Also check:
agent.*, not avatar.* (that's FULL)5 minutes of inactivity kills the session.
POST /v1/sessions/keep-alive with Bearer <session_token>{"type": "session.keep_alive", "event_id": "..."} via WebSocketSend every 2-3 minutes.
is_sandbox: true set in session tokendd73ea75-1218-4ef3-92ce-606d5f7fbc0a (sessions) or 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0 (embeds)~1 minute auto-termination is expected behavior.
Image avatars have no auto-generated voice. Specify voice_id in avatar_persona. Browse voices at GET /v1/voices.
LLM checklist:
secret_type: "LLM_API_KEY"model, secret_id, base_urlllm_configuration_id in session token/chat/completions protocolTTS checklist:
secret_type: "ELEVENLABS_API_KEY"POST /v1/voices/third_partywss:// for LiveKit and WebSocket*.livekit.cloud, api.liveavatar.com, embed.liveavatar.comGET /v1/sessions/{id}GET /v1/sessions/{id}/transcriptGET /v1/users/credits