Calls

A call is one live conversation. Your server decides who may start one and what the character knows; the client renders it and reports five states. Those are the only two surfaces you touch.

What your server decides

The session policy on your connect endpoint. Every field here is authoritative — whatever the browser sent for these is discarded, and a field you do not set is absent rather than inherited from the caller. The Field column is the SDK name; the Wire column is the key a hand-rolled request sends — snake_case and strict, see Calling the API directly below.

Two modes

Same character, same policy — only mode changes. A voice call draws on separate capacity, so it never competes with a video call.

What the client reports

Five states. Write copy for the ones you care about; the SDK ships none.

What you can do mid-call

call.say(text, { steer })  // say something to her; `steer` shapes THIS reply only
call.sayAndEnd(text)       // speak one exact line, verbatim, then close
call.keepAlive()           // the user is still here — postpone the idle disconnect
call.end()                 // end now
call.secondsRemaining      // to the hard stop, or null before the clock lands
call.queuePosition         // place in line while waiting, else null

# These are CLIENT-side actions — they act on a live call, which lives in the
# browser or native app. A Python backend owns the policy, not the live turn.
#
# What Python does own — and there is no Python SDK, so this half is plain HTTP:
#   POST /realtime/livekit/session           mint a call — body is snake_case and strict:
#                                            avatar_id, mode, instructions, initial_context,
#                                            max_session_seconds, stt_mode, capabilities,
#                                            transcript_webhook, client_metadata (the Wire
#                                            column above, not the SDK field names)
#   POST /realtime/livekit/session/release   free the slot early
#   GET  /credits/balance                    what the next call must fit inside

say(text, { steer }) is the hook for tool results — steer applies to one reply and then evaporates, so a lookup result cannot leak into every later turn. See Tool calling.

Ending well

A call that stops mid-sentence feels broken no matter how good the render was. When time is nearly up you get a callback and a handle; whatever you pass to sayAndEnd is spoken exactly as written — never rewritten by the model, never interrupted — and only then does the call close.

<AvatarCall
  client={client}                                  // createProxyClient({ proxyUrl })
  avatarId={avatarId}
  balanceMs={creditRemainingMs}

  onEnding={async ({ secondsLeft, call }) => {
    if (secondsLeft > 15) return;                 // wait for the last window
    call.sayAndEnd(await writeGoodbye(character));
  }}
  onQuiet={({ secondsLeft }) => toast(`Still there? (${secondsLeft}s)`)}
  onLowBalance={({ secondsLeft }) => openTopUp(secondsLeft)}
  onEnded={({ reason }) => showEndScreen(reason)}
/>

onEnded always carries one of user_ended · session_cap · idle · disconnected · out_of_credits · agent_ended · failed. Key your end screen off it — "talk again?" and "you're out of minutes" are different screens with different outcomes.

The idle timer is real and enforced: when it fires the client disconnects and capacity is freed. That is deliberate. An abandoned tab holding a live character is the most expensive thing that can happen in this product, and it would be on your bill.

You can also release a call from your server. rta.endCall(sessionId, { reason }) frees the slot immediately — best-effort and idempotent: true when acknowledged, false for anything else, never a throw, so calling it twice (or on a call that already ended) is safe. Reach for it when your backend learns the call is over before the client does: a webhook, an admin action, a superseded reconnect. (Wire: POST /realtime/livekit/session/release, realtime:write scope.)

From the client, call.end() is the same thing and is what you normally want. The SDK also sends a release on tab-close via releaseLiveKitSessionBeacon(), which survives the page going away where a normal fetch would not. Release early and often: a held slot is capacity nobody else can use, and the queue is shared.

Calling the API directly

Not on TypeScript? The same call is one authenticated POST — the Python tab on Quickstart has a working endpoint. Two things to know before hand-rolling it:

• Every endpoint is strict, and casing is per endpoint. An unknown or mis-cased key is a rejected call, not a dropped field — and which casing is right depends on where you are writing. The realtime routes on this page (/realtime/livekit/session and its /release) are snake_case; every REST resource endpoint — avatars, clips, keys, assets — is camelCase. Measured against the published spec: 2 of the 9 request bodies are snake_case at the top level and 7 are camelCase — with one exception worth knowing, because the strictness above turns it into a 422: POST /avatars is camelCase outside and snake_case inside voice (auto_description, voice_id). The SDK translates its camelCase policy for you; a hand-rolled request has no such help — send the Wire column from the policy table above (initial_context, max_session_seconds, transcript_webhook, client_metadata…), never the SDK names.
• Pass the connection payload to your client byte-for-byte. It is validated strictly — add one key and the client rejects the whole thing, so the call never opens and nothing points at the cause.

Full endpoint list, scopes, and error codes: API reference.