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.

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: [ ] Sample rate is exactly 24,000 Hz [ ] Raw PCM (no WAV/MP3/OGG headers) [ ] 16 bit signed, not 8 bit or 32 bit float [ ] Base64 encoded [ ] Chunks under 1MB 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 [ ] is sandbox: true set in session token [ ] Avatar ID is dd73ea75 1218 4ef3 92ce 606d5f7fbc0a (sessions) or 65f9e3c9 d48b 4118 b73a 4ae2e3cbb8f0 (embeds) [ ] Not using a different avatar with sandbox mode ~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: [ ] Secret: secret type: "LLM API KEY" [ ] Config: correct model , secret id , base url [ ] llm configuration id in session token [ ] Endpoint supports OpenAI /chat/completions protocol TTS checklist: [ ] Secret: secret type: "ELEVENLABS API KEY" [ ] Voice imported via POST /v1/voices/third party [ ] Using the returned LiveAvatar voice id (not the ElevenLabs ID) 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 1. Start with sandbox mode to eliminate billing issues 2. Check session state: GET /v1/sessions/{id} 3. Check transcript: GET /v1/sessions/{id}/transcript 4. Check credits: GET /v1/users/credits 5. Verify you're not mixing FULL and LITE event systems

liveavatar-debug