WebSocket /v1/live/sessions
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:
- Keep the fixed part of your
instructionsfirst, and keep it identical between sessions. - Put text that changes for each call at the end of
instructions. Examples are the current date and time, caller details, and conversation context. - Send
session.startbefore the person speaks. For example, open the session when the call connects or when the page is ready. - Send audio after
session.startedwhen 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.
Session events
Send JSON text frames after the connection opens.
Every event has a type.
A client can supply an event_id; related acknowledgments and errors return it as client_event_id.
Server events have their own event_id.
See Connect a live session for session.start parameters.
Client events
| Event | Fields beyond type and optional event_id |
Behavior |
|---|---|---|
session.start |
session |
Starts the session. This must be the first event. |
session.input_audio.append |
audio: Base64 string |
Sends input audio in the session format. |
session.input_audio.mute |
None | Replaces input with silence. Replies and delegated work continue. |
session.input_audio.unmute |
None | Restores input audio. |
session.commentary.append |
content: nonempty string; delegation_id: string or null |
Supplies a result or context that the voice can say. |
session.instructions.append |
Same fields as commentary | Adds trusted instructions for the voice. These can interrupt speech. They do not change backend instructions. |
session.thinking.append |
Same fields as commentary | Adds silent context. The voice can use it later. |
response.item.create |
item: object |
Supplies a function result or a text message in backend mode. |
response.create |
None | Continues the backend after tool results, or starts a backend response. |
session.update |
session.delegation: object |
Updates backend settings for later requests. The delegation object must include its unchanged type. |
session.close |
None | Ends the session with reason close_requested. |
Each context append permits at most 500 tokens.
Use the ID from session.delegation.created for client delegation results.
Several commentary updates can use the same completed client delegation ID.
Use null or omit delegation_id for context unrelated to a client delegation.
Backend mode refuses a non-null delegation_id on a context append.
A function result uses this shape:
{"type":"response.item.create","item":{"type":"function_call_output","call_id":"<call_id>","output":"The requested task is complete."}}
Send response.create after the function results.
A text message uses item.type: "message", a text content array, and role user, developer, system, or assistant.
The message remains available as context for later responses.
session.update accepts only session.delegation.
Its responses object accepts the backend settings in Connect a live session.
The delegation type, delegation mode, voice, audio format, and storage choice cannot change during a session.
Server events
| Event | Fields | Meaning |
|---|---|---|
session.started |
session |
The server accepted the start parameters. |
session.updated |
session, optional client_event_id |
The server accepted an update. |
session.output_audio.delta |
delta |
Base64 output audio in the session format. |
session.output_audio.cleared |
event_id |
Stop the current reply's playback. Drop its queued audio. Later audio belongs to the next reply. |
session.input_transcript.delta |
delta, start_ms, end_ms |
Recognized input text, with times on the input audio timeline. |
session.output_transcript.delta |
delta, start_ms, end_ms |
Spoken output text. The text follows estimated playback time. |
session.input_audio.muted |
Optional client_event_id |
Input is muted. |
session.input_audio.unmuted |
Optional client_event_id |
Input is unmuted. |
session.commentary.appended |
start_ms, end_ms, optional client_event_id |
The server accepted commentary. |
session.instructions.appended |
start_ms, end_ms, optional client_event_id |
The server accepted instructions. |
session.thinking.appended |
start_ms, end_ms, optional client_event_id |
The server accepted silent context. |
session.delegation.created |
delegation, offset_ms, optional client_event_id |
A task needs external work. See the fields below. |
response.event |
delegation_id, event |
A client-visible backend Responses event. |
session.usage.updated |
usage.seconds, context_window.usage_ratio |
Session time and context use, sent every 15 seconds. |
session.closed |
reason, session, usage.seconds |
The session ended. |
error |
error, optional client_event_id |
The server refused an event or reports a failure. |
A delegation object contains id, type: "delegation", and target (client or responses).
Backend mode also supplies delegation.response_id.
The event carries offset_ms at its top level.
In backend mode, session.delegation.created can also carry client_event_id after a client response.create.
The event contains no task text; a client uses the transcripts for context.
The session resource contains id, model, status, expires_at, audio, delegation, store, and input.
It includes nonempty instructions.
audio.output.voice reports the effective voice, including the default.
expires_at is a Unix timestamp in seconds.
Close reasons are close_requested, expired, and connection_lost.
After session.close, an active backend response can forward events for up to ten seconds before session.closed.
Session duration excludes that wait.
Admission errors
| HTTP status | error.code |
Meaning |
|---|---|---|
401 |
invalid_api_key |
Missing or invalid credentials. |
402 |
insufficient_funds |
The organization lacks funds. |
403 |
insufficient_scope |
The key cannot open a paid session. |
429 |
session_limit |
Session capacity is full. Retry after a session ends. |
503 |
server_error |
Session admission is unavailable. Retry after service recovery. |
Header clients receive these errors before the WebSocket opens.
Browser clients receive one error event followed by a close, as Connect a live session describes.
A capacity refusal can precede credential validation.
Event errors
The error object contains type, code, and message.
It includes param when a field caused the error.
An invalid start closes with code 1008.
A refused event after startup generally leaves the session open.
error.code |
Cause |
|---|---|
invalid_request |
Invalid event shape, invalid Base64 audio, empty context, or an invalid delegation or function-call ID. |
invalid_value |
Invalid voice or delegation mode, or text above its token limit. |
array_above_max_length |
More than 128 initial messages. |
unknown_parameter |
An unsupported field in session.update. |
missing_required_parameter |
A required update field is absent. |
immutable_field_update |
An update changes the delegation type or mode. |
unsupported_field |
A start field, backend setting, or requested storage option is unsupported. |
unknown_event |
The event type is unknown. |
unsupported_event |
A second session.start is not served after startup. |
model_not_found |
The session model is wrong or the backend model is unavailable. |
input_audio_rate_limit_exceeded |
Input audio exceeds the accepted rate. Pace audio at real time. |
engine_unavailable |
The session cannot start, or voice validation is unavailable. |
engine_error |
Speech processing failed during the session. |
recording_failed |
The session recording was not saved. |
{"type":"error","event_id":"event_1","error":{"type":"invalid_request_error","code":"invalid_value","message":"delegation.mode must be off, auto, or always.","param":"session.delegation.mode"}}

