Connect a live session

Connect to wss://api.resia.ai/v1/live/sessions. One WebSocket connection carries one session. Send events as JSON text frames.

Authentication

Client Credentials
Server Authorization: Bearer <Resia API key>
Browser Offer both WebSocket subprotocols: resia-fullplex and resia-id-token.<token>. Use only a signed-in organization member's portal ID token.

Keep API keys on your server. Never send an API key to a browser or a mobile app. For an app used by other people, send its audio through your server.

The server selects only resia-fullplex as the browser subprotocol. It does not echo the token. An Authorization header takes priority over subprotocol credentials. Never put credentials in a URL.

A header client receives an HTTP error if admission fails. A browser receives an open socket followed by one error event and a close. A browser refusal closes with code 1013 for HTTP-equivalent 429 or 503; other admission refusals close with 1008. See Session events for the errors.

Start parameters

Send session.start as the first event after the connection opens. The session object accepts these fields:

Field Type Required Value or default
model string Yes resia-fullplex-1.
instructions string No Conversation instructions; at most 16,384 tokens. Absent or null selects the default instructions.
input array No Prior messages; at most 128 messages and 8,192 tokens in total. Absent or null selects an empty array.
audio.format object No One of the formats below. Default: PCM at 24,000 samples per second.
audio.output.voice string or null No cartesia:<voice ID> or fish:<voice ID>. Absent or null selects Cartesia Skylar.
delegation object or null No Client mode by default; see Delegation below.
delegation.mode string or null No off, auto, or always. Absent or null selects auto. Fixed for the session.
store boolean No false by default. true saves a session recording.

Each prior message has type: "message", a role of developer, user, or assistant, and one text content part. Use {"type":"input_text","text":"..."} for a developer or user message. Use {"type":"output_text","text":"..."} for an assistant message.

{"type":"session.start","session":{"model":"resia-fullplex-1","instructions":"Help the caller.","store":false,"audio":{"format":{"type":"audio/pcm","rate":24000}},"delegation":{"type":"client"}}}

The server returns session.started with the session resource. An invalid start produces an error event followed by close code 1008.

Start a session fast

The server sends session.started when the session is ready to talk. The time to session.started grows with the length of instructions. The time drops when the beginning of your instructions is the same in every session, because the server can reuse that part. Use these practices to shorten the wait before the first reply:

  1. Keep the fixed part of your instructions first, and keep it identical between sessions.
  2. Put text that changes for each call at the end of instructions. Examples are the current date and time, caller details, and conversation context.
  3. Send session.start before the person speaks. For example, open the session when the call connects or when the page is ready.
  4. Send audio after session.started when you can.

Audio that you send before session.started is not lost. The server holds it and processes it after the session starts. The first reply still comes after session.started, so an early start gives the shortest wait.

Audio formats

Input and output use the same format. Encode audio bytes as Base64 in session.input_audio.append.audio. Decode session.output_audio.delta.delta before playback.

audio.format.type audio.format.rate Audio bytes
audio/pcm 24000 or 16000 Mono, signed 16-bit little-endian PCM.
audio/pcmu 8000 G.711 mu-law.
audio/pcma 8000 G.711 A-law.
{"type":"session.input_audio.append","audio":"AAA="}

When session.output_audio.cleared arrives, stop playback of the current reply. Drop its queued audio. Audio after that event belongs to the next reply.

Voice selection

Retrieve voice IDs from GET /v1/live/available-voices. Select one through session.audio.output.voice before the session starts. The voice cannot change during a session.

Fish is unavailable to an organization that requires a business associate agreement or zero data retention. The Fish catalog returns an empty list for that organization. Cartesia is available under either requirement. A private voice does not appear in the catalog; use an ID that Resia supplied for your use.

Delegation

Delegation gives a task from the conversation to your application or a backend assistant. The delegation type and mode stay fixed for the session.

Setting Behavior
delegation: null, absent, or {"type":"client"} Your application receives session.delegation.created. It returns results through context append events.
{"type":"responses","responses":{...}} A backend assistant performs the task. The server forwards its public events through response.event.
delegation.mode: "off" The session does not delegate tasks.
delegation.mode: "auto" The session selects when to delegate.
delegation.mode: "always" The session delegates replies to completed caller turns, subject to the conversation state.

Backend settings live in delegation.responses:

Field Type Required Purpose
model string Yes A backend model available to your organization.
instructions string No Backend instructions.
tools array No Function tools, MCP tools, web search, or image generation.
tool_choice string or object No Tool selection.
parallel_tool_calls boolean No Permit parallel tool calls.
max_output_tokens positive integer No Maximum backend output tokens.
reasoning object No Backend reasoning settings.
text object No Backend text settings.

Function tools execute on your client. MCP means Model Context Protocol; these tools connect through the backend provider. The API refuses service_tier, file search, code execution, provider file references, stored prompts, conversations, and previous_response_id. An unsupported setting produces an error that names the field. Use session.update to change supported backend settings for later work. See Session events.