Skip to main content
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.
​
Authorization
string
required
Bearer token obtained from the authenticate endpoint.
​
integration_id
string
required
ID of the database integration to use for voice queries.
​
chat_id
string
ID of an existing chat to continue the conversation. Omit to create a new chat.

​
Response

​
room_name
string
required
Unique LiveKit room name for this session.
​
token
string
required
Signed JWT token for connecting to the LiveKit room. Valid for 2 hours.
​
livekit_url
string
required
LiveKit WebSocket URL to connect to (e.g., wss://your-project.livekit.cloud).
​
expires_in_seconds
integer
required
Token validity duration in seconds (7200).
​
chat_id
string
required
Chat ID for this session. Either the provided chat_id or a newly created one.

​
How it works

​
Connecting to the room

Use the returned token and livekit_url to connect with the LiveKit client SDK:
React Native
import { useRoom, AudioSession } from "@livekit/react-native";

// Start audio session (required on mobile)
await AudioSession.startAudioSession();

// Connect to the room
const { connect } = useRoom();
await connect(livekitUrl, token, {
  autoSubscribe: true,
});

curl -X POST https://api.trellis.sh/v1/voice/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

import requests

response = requests.post(
    "https://api.trellis.sh/v1/voice/sessions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "integration_id": "550e8400-e29b-41d4-a716-446655440000",
    },
)

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({
    integration_id: "550e8400-e29b-41d4-a716-446655440000",
  }),
});

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": "Authentication required"
}

{
  "detail": "Integration not found"
}

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