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
/realtime-sessionsCreates 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_idstringrequiredagent_namestringoptionalagent_idstringoptionaldefinition_id.system_promptstringoptionalmodelstringoptionalstt_modelstringoptionaltiny.en.voicestringoptionalen_US-lessac-medium.languagestringoptionalauto to detect it per utterance. Default: the agent's voice settings.code_agent_version_idstringoptionalplayground_session_idstringoptionalSend one of agent_name, agent_id, or system_prompt with model.
Response fields
room_namestringoptionaltokenstringoptionallivekit_urlstringoptionalResponses
Retry-After.List voice sessions
/realtime-sessionsThe project's sessions, newest first.
Query parameters
project_idstringrequiredResponse fields
sessions[].idstringoptionalsessions[].modelstringoptionalsessions[].voicestringoptionalsessions[].stt_modelstringoptionalsessions[].agent_idstring or nulloptionalsessions[].statusstringoptionalactive or closed.sessions[].close_reasonstring or nulloptionalabandoned means the room disappeared without the worker reporting an end.sessions[].started_atstringoptionalsessions[].ended_atstring or nulloptionalGet a session's events
/realtime-sessions/{session_id}/eventsEverything 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 path | Who | What it does |
|---|---|---|
GET /projects/{project_id}/agents/{agent_name}/voice-settings | viewer | How the agent runs on a call. An agent without settings answers every default. |
PUT /projects/{project_id}/agents/{agent_name}/voice-settings | developer or admin; licence realtime | Body: 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 path | Who | What it does |
|---|---|---|
POST /realtime-sessions/{session_id}/hangup | developer or admin | End a phone call. |
POST /realtime-sessions/{session_id}/transfer | developer or admin | Send a phone caller to one of the number's transfer targets: {"target": "<name>"}. |
GET /realtime-sessions/{session_id}/recording | developer or admin | The call's recording, as a stereo WAV file. Each read is audited. |
See Telephony for trunks, numbers and outbound calls.