liveavatar-debug — Claude Code skill: debug 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"
---

# 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