> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellis.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Voice Session

> Create a LiveKit voice session for real-time voice chat

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.

<Note>
  For mobile integration, use the [LiveKit React Native SDK](https://docs.livekit.io/client-sdk-js/react-native/) (`@livekit/react-native`) to connect to the room with the returned token.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the authenticate endpoint.
</ParamField>

<ParamField body="integration_id" type="string" required>
  ID of the database integration to use for voice queries.
</ParamField>

<ParamField body="chat_id" type="string">
  ID of an existing chat to continue the conversation. Omit to create a new chat.
</ParamField>

## Response

<ResponseField name="room_name" type="string" required>
  Unique LiveKit room name for this session.
</ResponseField>

<ResponseField name="token" type="string" required>
  Signed JWT token for connecting to the LiveKit room. Valid for 2 hours.
</ResponseField>

<ResponseField name="livekit_url" type="string" required>
  LiveKit WebSocket URL to connect to (e.g., `wss://your-project.livekit.cloud`).
</ResponseField>

<ResponseField name="expires_in_seconds" type="integer" required>
  Token validity duration in seconds (7200).
</ResponseField>

<ResponseField name="chat_id" type="string" required>
  Chat ID for this session. Either the provided `chat_id` or a newly created one.
</ResponseField>

## How it works

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant App as Mobile App
    participant API as Trellis API
    participant LK as LiveKit Cloud
    participant Agent as Voice Agent

    App->>API: POST /v1/voice/sessions
    API-->>App: room_name, token, livekit_url
    App->>LK: Connect with token
    LK->>Agent: Auto-dispatch agent to room
    App->>LK: Send audio (speak)
    LK->>Agent: Forward audio stream
    Agent->>LK: Stream TTS response
    LK->>App: Receive audio (listen)
```

## Connecting to the room

Use the returned `token` and `livekit_url` to connect with the LiveKit client SDK:

```typescript React Native theme={"theme":{"light":"github-light","dark":"github-dark"}}
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,
});
```

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"]
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "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"
  }
  ```

  ```json 401 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Authentication required"
  }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Integration not found"
  }
  ```

  ```json 503 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Voice chat is not configured"
  }
  ```
</ResponseExample>