Liveavatar Debug
- 631 installs
- 5 repo stars
- Updated July 30, 2026
- heygen-com/liveavatar-agent-skills
liveavatar-debug is a version 1.0.0 agent skill that triages HeyGen LiveAvatar production failures including silent streams, webhook timeouts, avatar state drift, and API errors during live sessions.
About
liveavatar-debug is a HeyGen agent skill (version 1.0.0, MIT license) for symptom-based troubleshooting of LiveAvatar integrations in production. It addresses silent or unresponsive avatars—often caused by a missing context_id in FULL mode that restricts input without throwing errors—garbled audio, sessions that fail to start, missing webhook events, and HeyGen API error codes. Follow the skill's decision tree from symptom to fix rather than re-reading generic API docs. Invoke it when a deployed LiveAvatar agent streams video but ignores speech, webhooks time out, or session state drifts during live user interactions.
- LiveAvatar failure triage
- Stream and session diagnostics
- HeyGen API error patterns
- Webhook and callback debugging
- Production incident playbooks
Liveavatar Debug by the numbers
- 631 all-time installs (skills.sh)
- +43 installs in the week ending Aug 2, 2026 (Skillselion tracking)
- Ranked #69 of 596 Debugging skills by installs in the Skillselion catalog
- Data as of Aug 2, 2026 (Skillselion catalog sync)
npx skills add https://github.com/heygen-com/liveavatar-agent-skills --skill liveavatar-debugAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 631 |
|---|---|
| repo stars | ★ 5 |
| Last updated | July 30, 2026 |
| Repository | heygen-com/liveavatar-agent-skills ↗ |
Why is my LiveAvatar integration silent or failing?
Triage LiveAvatar agent failures in production: broken streams, webhook timeouts, avatar state drift, and HeyGen API errors during live sessions.
Who is it for?
Developers operating HeyGen LiveAvatar agents in production when streams, webhooks, or session state fail during live user sessions.
Skip if: Greenfield LiveAvatar integration design with no deployed symptoms to diagnose.
When should I use this skill?
LiveAvatar avatar is silent, audio is garbled, sessions fail to start, webhooks are not received, or HeyGen API errors appear in production.
What you get
Root-cause diagnosis, context_id and mode fixes, webhook configuration corrections, and API error remediation steps
- Root-cause diagnosis
- Configuration fix steps
- Webhook remediation checklist
By the numbers
- Skill version 1.0.0 in heygen-com/liveavatar-agent-skills metadata
Files
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 fromagent-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.*, notavatar.*(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-alivewithBearer <session_token> - LITE:
{"type": "session.keep_alive", "event_id": "..."}via WebSocket
Send every 2-3 minutes.
Sandbox won't start
- [ ]
is_sandbox: trueset in session token - [ ] Avatar ID is
dd73ea75-1218-4ef3-92ce-606d5f7fbc0a(sessions) or65f9e3c9-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_idin session token - [ ] Endpoint supports OpenAI
/chat/completionsprotocol
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
Related skills
Azure DiagnosticsSystematically diagnose and resolve production issues on Microsoft Azure using official Microsoft guidance.495k1.3kAzure MessagingQuickly diagnose and fix connection, authentication, and message-processing failures when using Azure Event Hubs or Service Bus SDKs.483k1.3k
Diagnosing BugsGet a systematic, step-by-step process that surfaces the real root cause instead of guessing at bugs.291k200k
Use My BrowserWhen their agent task requires access to the live browser session, rendered DOM state, authenticated dashboards, localhost apps, or DevTools-selected elements instea269k71
Systematic DebuggingFollow a repeatable four-phase process that forces root-cause discovery before any code changes.210k265k
Safe DebugGet conservative, non-destructive diagnosis of deep learning and agent errors before any code changes are made.185k512How it compares
Use liveavatar-debug for production symptom triage; use LiveAvatar integration skills for initial API wiring and session setup.
FAQ
Why is a LiveAvatar silent with no error thrown?
liveavatar-debug identifies missing context_id in FULL mode as the top cause: the avatar streams video but enters restricted mode and ignores user input. Creating and passing context_id restores speech handling.
What symptoms does liveavatar-debug cover?
liveavatar-debug covers silent or unresponsive avatars, garbled audio, sessions that fail to start, webhook events not received, and HeyGen API errors—each with a symptom-to-fix troubleshooting path.