Skip to main content

Voice sessions

A voice session is a LiveKit room in your cluster with the voice worker in it. These endpoints need a Keycloak access token and the developer or admin role on the project. See Voice agents for what a session needs.

Start a voice session​

POST/realtime-sessions

Creates a room, sends the voice worker into it and returns a token your client uses to join. Name an agent, or give a system prompt and a model directly.

Body​

project_idstringrequired
The project.
agent_namestringoptional
Run the live version of this agent.
agent_idstringoptional
Run this exact agent version, by definition_id.
system_promptstringoptional
Instead of an agent: the instructions.
modelstringoptional
Instead of an agent: the chat model reference.
stt_modelstringoptional
The speech-to-text model reference. Default: the agent's voice settings, else tiny.en.
voicestringoptional
The text-to-speech model reference. Default: the agent's voice settings, else en_US-lessac-medium.
languagestringoptional
The caller's language, as an ISO 639-1 code, or auto to detect it per utterance. Default: the agent's voice settings.
code_agent_version_idstringoptional
For a code agent, the version to call. Default: the live one.
playground_session_idstringoptional
Save the spoken turns to this Playground session.

Send one of agent_name, agent_id, or system_prompt with model.

Response fields​

room_namestringoptional
The room, which is also the session id.
tokenstringoptional
A LiveKit access token that lets one participant join this room.
livekit_urlstringoptional
The LiveKit address to connect to.

Responses​

200
The session started.
400
Both an agent and a prompt were sent, the agent has no model, or the speech-to-text model or voice is not built in the catalog.
403
You are not a developer or admin on the project.
404
No such agent.
409
The agent has no live version, or the Playground session belongs to another project or target.
502
LiveKit could not be reached.
503
All voice sessions are in use. Retry after the time in Retry-After.

List voice sessions​

GET/realtime-sessions

The project's sessions, newest first.

Query parameters​

project_idstringrequired
The project.

Response fields​

sessions[].idstringoptional
The session id.
sessions[].modelstringoptional
The chat model.
sessions[].voicestringoptional
The text-to-speech model.
sessions[].stt_modelstringoptional
The speech-to-text model.
sessions[].agent_idstring or nulloptional
The agent version, if the session ran one.
sessions[].statusstringoptional
active or closed.
sessions[].close_reasonstring or nulloptional
How it ended. abandoned means the room disappeared without the worker reporting an end.
sessions[].started_atstringoptional
When it started.
sessions[].ended_atstring or nulloptional
When it ended.

Get a session's events​

GET/realtime-sessions/{session_id}/events

Everything the voice worker reported for one session, oldest first: what was said, tool calls and how the session ended. Each event has id, event_type, payload and created_at.

Voice settings​

Method and pathWhoWhat it does
GET /projects/{project_id}/agents/{agent_name}/voice-settingsviewerHow the agent runs on a call. An agent without settings answers every default.
PUT /projects/{project_id}/agents/{agent_name}/voice-settingsdeveloper or admin; licence realtimeBody: voice, stt_model, pipeline (auto, direct or workflow), talker_model, handoff_model, filler_text, approval_wait_seconds (60 to 1800, default 120), language, voices_by_language (language code to voice).

The models are checked against the catalog and the project's model access. A Whisper .en model can't take a language other than English or detect one, and a Piper voice can be mapped only to the language it speaks. See Voice agents.

Calls in progress​

Method and pathWhoWhat it does
POST /realtime-sessions/{session_id}/hangupdeveloper or adminEnd a phone call.
POST /realtime-sessions/{session_id}/transferdeveloper or adminSend a phone caller to one of the number's transfer targets: {"target": "<name>"}.
GET /realtime-sessions/{session_id}/recordingdeveloper or adminThe call's recording, as a stereo WAV file. Each read is audited.

See Telephony for trunks, numbers and outbound calls.

Was this page helpful?