Troubleshooting
What to check when the AI persona is silent, can't hear the person, hears itself, or a conversation won't start.
The AI persona's video plays but there is no sound
Browsers block audio until the person interacts with the page. Start the conversation from a click or a tap, not when the page loads, and attach the persona's audio track to an element that plays, as Connect does.
The persona doesn't hear the person
- No microphone published. Publish it as soon as you join the room.
session.startedcomes once the persona can hear it; without one, it comes about 2 seconds after you join, and the persona hears nothing until you publish. - No permission. The browser or the platform refused the microphone. Ask the person to allow it in their settings.
- Muted. After
session.input_audio.mute, the persona hears the microphone as silence untilsession.input_audio.unmute.
The persona answers itself
The persona hears its own voice through the person's speaker. Capture the microphone with echo cancellation on, as Connect says. With it on, this happens mostly with external speakers at high volume: ask the person to use headphones or turn the volume down.
The conversation takes a while to start
A conversation never waits in a line, but its start can take a little while:
- The persona is getting ready. The events route's
preparingsays a runtime is held and getting ready, which can take up to about half a minute. - No capacity right now.
POST /conversationanswers429capacity_unavailable: try again afterretry_after_seconds. - Too many starts at once.
POST /conversationanswers503busy: try again afterretry_after_seconds.
Show the person that the persona is on its way, so the wait doesn't look like a fault. If the person cancels before admitted, call POST /conversation/{id}/abandon.
A conversation won't start
Read the status and code the API answers. Errors lists each one. The most common:
capacity_unavailable(429). No capacity could take the conversation right now. Nothing was spent: let the person try again in a moment.concurrency_limit(409). Your API keys already run as many conversations as your plan allows. End one first.policy_curfew(403). New conversations are paused after repeated violations of our Acceptable Use Policy. See Safety.not_authenticated(401). The session token expired or was used already. Mint a new token for each conversation, right before it starts.
The persona doesn't speak, or a session seems stuck
See When nothing happens.
A conversation ends early
session.closed says why with reason, and the events route's ended follows. The session's end lists each reason.