Create Voice Session

Create a voice chat session and receive LiveKit connection details. The Trellis voice agent automatically joins the room when the client connects, enabling real-time voice conversations with your database.

For mobile integration, use the LiveKit React Native SDK (@livekit/react-native) to connect to the room with the returned token.

string

required

Bearer token obtained from the authenticate endpoint.

string

ID of an existing chat to continue the conversation. Omit to create a new chat. A malformed, unknown, or out-of-scope ID also creates a new chat instead of returning an error, so always use the chat_id returned in the response. The voice session derives its datasource from the chat’s agent — there is no integration_id on this request.

string

Optional model override for durable voice turns. Use an id returned by List Models. If the voice service falls back to legacy in-process generation, that fallback uses its configured model instead.

string

Optional client-generated correlation id, threaded through to the voice agent so a single session can be reconstructed end-to-end in telemetry. See Voice Timing.

Response

string

required

Unique LiveKit room name for this session.

string

required

Signed JWT token for connecting to the LiveKit room. Valid for 2 hours.

string

required

LiveKit WebSocket URL to connect to (e.g., wss://your-project.livekit.cloud).

integer

required

Token validity duration in seconds (7200).

string

required

Authoritative chat ID for this session. It can differ from the requested ID when the request did not identify an accessible existing chat.

How it works

Register the agent_events text-stream handler before connecting so the client cannot miss an early agent_ready or greeting event:

JavaScript

import { Room } from "livekit-client";

const room = new Room();

room.registerTextStreamHandler("agent_events", async (reader) => {
  const event = JSON.parse(await reader.readAll());
  handleVoiceEvent(event);
});

await room.connect(livekitUrl, token, {autoSubscribe: true});

On mobile, start the platform audio session before connecting as required by your LiveKit SDK.

`agent_events` payloads

Events are JSON objects published on the LiveKit text-stream topic agent_events. Delivery is best-effort; persisted chat messages remain the source of truth.

`type`	Fields
`agent_ready`	`backend_t0_ms` (Unix epoch milliseconds)
`message`	`message_id`, `chat_id`, `role`, `content`, optional `turn_id`
`tool_call`	`message_id`, `chat_id`, `tool`, `tool_call_id`, `args`, optional `turn_id`
`tool_result`	`message_id`, `chat_id`, `tool_call_id`, `preview`, optional `inline`, optional `turn_id`
`transcript_rejected`	`chat_id`, `reason`, optional `content`

Only client-facing data-tool calls and results are published. inline is present only when the result is small enough to send directly on the live path; it can also be null on the durable path. Treat a missing or null value as a degraded preview and reconcile from the persisted chat after the turn. Durable events can use synthetic message_id values beginning with voice-, which are not retrievable message IDs.

tool_result

{
  "type": "tool_result",
  "message_id": "8a07b85a-0a69-4d8b-9d89-53b6933adcb1",
  "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45",
  "tool_call_id": "tc_1",
  "preview": "kind, columns, rows",
  "inline": {
    "kind": "table",
    "columns": [{"name": "project_name", "type_hint": "string"}],
    "rows": [["Saadiyat Lagoons"]],
    "row_count": 1,
    "truncated": false
  }
}

Session lifecycle

There is no end-session API call. Disconnect from the LiveKit room to end the client session. The room token is valid for 7,200 seconds; create a new session after it expires. Voice messages are persisted in the returned chat. Creating another voice session with that accessible chat_id reloads the conversation and suppresses the new-chat greeting when prior messages exist.

curl -X POST https://api.trellis.sh/v1/voice/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45"
  }'

import requests

response = requests.post(
    "https://api.trellis.sh/v1/voice/sessions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45",
    },
)

session = response.json()
room_name = session["room_name"]
token = session["token"]
livekit_url = session["livekit_url"]

const response = await fetch("https://api.trellis.sh/v1/voice/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chat_id: "8f14e45f-ceea-467f-a83c-0a06b8901a45",
  }),
});

const { room_name, token, livekit_url } = await response.json();

{
  "room_name": "trellis-voice-550e8400-a1b2c3d4",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "livekit_url": "wss://trellis-abc123.livekit.cloud",
  "expires_in_seconds": 7200,
  "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45"
}

{
  "detail": "Missing Authorization header"
}

{
  "detail": "Voice chat is not configured"
}

Overview

Authentication

Agents

Datasources

Saved Queries

Models

Chats

Artifacts

Jobs

Voice

Audio

User Memories

Organization Rules

Admin

Response

How it works

`agent_events` payloads

Session lifecycle

​Response

​How it works

​Connect and subscribe to structured events

​agent_events payloads

​Session lifecycle

Response

How it works

Connect and subscribe to structured events

`agent_events` payloads

Session lifecycle