Skip to main content
For problems with the 3D avatar, see Open Source troubleshooting.

​
Realistic Avatars

The API key is invalid, revoked or missing. Check that TALKING_AVATAR_API_KEY is set on the server, has no extra spaces or quotes, and still appears on the dashboard’s API keys page. Create a new key if you lost it: keys are shown only once.
Your balance is below one minute ($0.02), it ran out during the session, or you reached your monthly spending limit. Add credits on Billing, turn on auto top-up, or raise the limit.
Sessions can run for up to 3 hours. Start a new session to continue.
Node.js 18 and 20 have no global WebSocket. Upgrade to Node.js 22, or install ws and pass it in:
Browsers block sound until the user interacts with the page. Call view.connect() from a click. If the status is muted, show a button that calls view.unmute().
Your app still plays the agent’s audio somewhere else (an <audio> element, a speaker stream, or track.attach() in LiveKit). The avatar plays the voice itself; remove the other playback.
The sampleRate doesn’t match your audio, or the audio isn’t raw PCM16 mono. Ask your TTS for raw PCM, pass its exact sample rate, and decode MP3, Opus or WAV (and strip WAV headers) first. See Stream audio.
  • Check that your /avatar route returns avatar.handleView(req.body) as JSON, and parses JSON bodies.
  • Check that the LiveAvatar for that conversation is still running (not closed).
  • Users behind strict firewalls may need a TURN server: pass it in iceServers.
You started the session with the livekit option. In LiveKit mode, the avatar joins your room and your LiveKit client plays it: you don’t need handleView or LiveAvatarView.

​
Voice Agents

The agent’s account can’t start calls. Check your balance (at least $0.02 is needed) and your monthly spending limit on Billing. Callers aren’t told why.
The agent is turned off (Share & embed → Taking calls), deleted, or private and opened without a valid link.
Create the agent first, and make sure Taking calls is on. Test calls use the last saved version.
The browser blocked the microphone. They should allow it in the browser’s site settings and try again. In an iframe, the embed code must include allow="microphone; autoplay".
That caller has started many calls to the same agent recently. They can try again later. This protects your balance from abuse.
The prompt still has [placeholders]. The Agent tab shows how many are left to fill in.
Adjust turn-taking: with Semantic, choose Patient to give callers more time, or Eager for faster replies. With Voice activity, raise Silence to wait longer.
  • Make the tool’s When to use it description specific, and mention the tool in the prompt.
  • Your endpoint must be HTTPS, answer POST with JSON within 10 seconds, and return a 2xx status.
  • The Calls tab shows how many tool calls each call made; your server’s logs show what it received.
Your endpoint didn’t answer with a 2xx within 10 seconds. Check that it’s public HTTPS, accepts POST JSON, and that signature checks use the raw body and the right secret. We don’t retry; the call and its transcript are still in the dashboard.
Verify against the raw request body (before JSON parsing), use the agent’s own secret (each agent has one), and update your servers after Rotate secret. See Verify signatures.
The private link is past its expiry, or has started its maximum number of calls (This link has no calls left). Make a new link.

​
Account and billing

Check spam, and that you typed your email correctly. Then complete the security check and click Send a new code. You can request up to 5 codes in 10 minutes.
There’s no account for that email yet. Create one, or sign in with Google if that’s how you signed up.
Credits are added a few seconds after payment, and the Billing page refreshes itself. If they still haven’t arrived after a few minutes, email support@talking-avatar.dev with your receipt.
Auto top-up needs a saved card. When you first enable it, click Save & add card and finish the checkout. If your card is declined or the saved card is removed, add it again the same way.
Still stuck? See Support.