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

# LiveKit

> Connect to LiveKit real-time communication platform for advanced audio/video agents

## Overview

LiveKit connection enables integration with agents built on LiveKit's real-time communication platform for audio, video, and data streaming. This connection type supports both LiveKit Cloud and self-hosted LiveKit deployments.

## Configuration Requirements

### Generate Token Endpoint

* **Field**: `generate_token_endpoint`
* **Type**: String (required)
* **Purpose**: Endpoint for generating LiveKit access tokens
* **Format**: Valid HTTPS URL
* **Example**: `https://your-api.com/livekit/token`

Coval sends a POST request to this endpoint with:

```json theme={null}
{
  "room_name": "uuid-generated-by-coval",
  "participant_name": "simulated_user"
}
```

Your endpoint should return:

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "serverUrl": "wss://your-livekit-server.com",
  "room_name": "uuid-generated-by-coval"
}
```

### LiveKit URL

* **Field**: `livekit_url`
* **Type**: String (required)
* **Purpose**: LiveKit server WebSocket URL
* **Format**: Valid WebSocket URL (wss\://)
* **Example**: `wss://your-livekit-server.com`

<Note>
  If your token endpoint returns `serverUrl` or `server_url`, that value will override this configuration.
</Note>

### Generate Token Headers

* **Field**: `generate_token_headers`
* **Type**: String (optional)
* **Purpose**: HTTP headers for token generation requests
* **Format**: Valid JSON string
* **Example**: `{"Authorization": "Bearer your-api-key", "Content-Type": "application/json"}`

### Sandbox ID

* **Field**: `sandbox_id`
* **Type**: String (optional)
* **Purpose**: LiveKit Cloud sandbox identifier for automatic agent dispatch
* **When to use**: Only required when using LiveKit Cloud's managed sandbox feature
* **When to skip**: Leave empty if self-hosting LiveKit or using your own agent dispatch system

<Info>
  **Sandbox ID is optional for most users.** It's a LiveKit Cloud-specific feature for automatic agent dispatch. If you're running your own LiveKit server or managing agent dispatch yourself, you don't need this field.
</Info>

### LiveKit Agent Name

* **Field**: `livekit_agent_name`
* **Type**: String (optional)
* **Purpose**: Name identifier for the LiveKit agent
* **Format**: String identifier
* **Example**: `"voice-assistant"`, `"video-agent"`

### LiveKit Agent Metadata

* **Field**: `livekit_agent_metadata`
* **Type**: String (optional)
* **Purpose**: Additional metadata for the LiveKit agent
* **Format**: String or JSON string
* **Example**: `"{'role': 'assistant', 'capabilities': ['voice', 'video']}"`

### Custom Payload Fields

* **Field**: `token_request_payload`
* **Type**: String (optional)
* **Purpose**: Additional fields to include in the token request
* **Format**: Valid JSON string
* **Example**: `{"agent_variant": "sales", "language": "en"}`

These fields are merged with `room_name` and `participant_name` when calling your token endpoint.

## Setup Instructions

1. Set up a token generation endpoint that accepts POST requests
2. Configure your endpoint to return tokens with the correct room permissions
3. Enter your LiveKit server WebSocket URL
4. (Optional) Add authentication headers if your endpoint requires them
5. Test the connection by launching a simulation

## Technical Details

### Token Generation Flow

1. Coval generates a unique room name (UUID) for each simulation
2. Coval sends a POST request to your token endpoint with the room name
3. Your endpoint generates a LiveKit JWT token with room access permissions
4. Your endpoint should also dispatch your agent to join the same room
5. Coval joins the room using the returned token
6. Coval waits for your agent to join (`on_first_participant_joined` event)
7. Conversation simulation begins

### Accepted Response Field Names

Coval accepts multiple field name variations for flexibility:

| Data       | Accepted Field Names                                                            |
| ---------- | ------------------------------------------------------------------------------- |
| Token      | `token`, `participantToken`, `accessToken`, `participant_token`, `access_token` |
| Server URL | `serverUrl`, `server_url`                                                       |
| Room Name  | `roomName`, `room_name`                                                         |

## Troubleshooting

### Common Issues

**Token Generation Failures**

* Check endpoint accessibility and authentication
* Verify your endpoint returns valid JSON with a `token` field
* Ensure HTTPS is properly configured

**WebSocket Connection Errors**

* Verify LiveKit server URL starts with `wss://`
* Check that `serverUrl` is included in your token response
* Confirm your LiveKit server is running and accessible

**Agent Not Joining Room**

* Ensure your agent dispatch system receives the `room_name` from token requests
* Verify your agent is running and connected to LiveKit
* Check that the token grants access to the correct room

**Simulation Timeouts**

* Coval waits for your agent to join before starting
* If your agent doesn't join, the simulation will timeout
* Check your agent logs for connection errors

**"No token found in response" Error**

* Verify your response includes a recognized token field name
* Check that the token value is a non-empty string
* Ensure response Content-Type is `application/json`

### Running Components Locally

Coval's servers need to reach your **token endpoint** and **LiveKit server** to run simulations. Here's what needs to be publicly accessible:

| Component          | Must be public? | Why                                       |
| ------------------ | --------------- | ----------------------------------------- |
| Token endpoint     | Yes             | Coval calls it to get access tokens       |
| LiveKit server     | Yes             | Coval connects via WebSocket              |
| Your LiveKit agent | No              | Only needs outbound connection to LiveKit |

**If running your token server locally:**
Use a tunneling service like [ngrok](https://ngrok.com) to expose it:

```bash theme={null}
ngrok http 8888
# Use the generated https:// URL as your token endpoint
```

<Note>
  Your agent can run on your local machine without any tunneling—it just connects outbound to the LiveKit server like any other client.
</Note>