| 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"} |
LiveAvatar Debugging Guide
Symptom-based troubleshooting for LiveAvatar integrations. Find your symptom below and follow the fix.
Avatar is silent / not responding to speech
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:
- Browser mic permissions blocked (check
allow="microphone" on iframe)
- Push-to-Talk enabled but PTT events not being sent
- OS-level mic mute
Audio is garbled or distorted (LITE Mode)
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.
401 error / session fails to start
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.
Events not received (FULL Mode)
- Subscribed to correct topics? Send to
agent-control, receive from agent-response
- LiveKit room connected? Check connection state
- Parsing JSON correctly? Events have
event_type, event_id, session_id
WebSocket events silently dropped (LITE Mode)
Most likely: Sending before connected.
Wait for {"type": "session.state_updated", "state": "connected"} before sending any commands.
Also check:
- Using correct event names? LITE uses
agent.*, not avatar.* (that's FULL)
- WebSocket still open? 5-min inactivity timeout
Session times out
5 minutes of inactivity kills the session.
- FULL:
POST /v1/sessions/keep-alive with Bearer <session_token>
- LITE:
{"type": "session.keep_alive", "event_id": "..."} via WebSocket
Send every 2-3 minutes.
Sandbox won't start
~1 minute auto-termination is expected behavior.
Image avatar fails / no audio
Image avatars have no auto-generated voice. Specify voice_id in avatar_persona. Browse voices at GET /v1/voices.
Custom LLM / TTS not working
LLM checklist:
TTS checklist:
CORS / network errors
- API calls should come from backend, not browser
- Allow outbound
wss:// for LiveKit and WebSocket
- Allow
*.livekit.cloud, api.liveavatar.com, embed.liveavatar.com
General approach
- Start with sandbox mode to eliminate billing issues
- Check session state:
GET /v1/sessions/{id}
- Check transcript:
GET /v1/sessions/{id}/transcript
- Check credits:
GET /v1/users/credits
- Verify you're not mixing FULL and LITE event systems