Skip to main content

​
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: 
{
  "room_name": "uuid-generated-by-coval",
  "participant_name": "simulated_user"
}
Your endpoint should return: 
{
  "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
If your token endpoint returns serverUrl or server_url, that value will override this configuration.

​
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
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.

​
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:
DataAccepted Field Names
Tokentoken, participantToken, accessToken, participant_token, access_token
Server URLserverUrl, server_url
Room NameroomName, 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:
ComponentMust be public?Why
Token endpointYesCoval calls it to get access tokens
LiveKit serverYesCoval connects via WebSocket
Your LiveKit agentNoOnly needs outbound connection to LiveKit
If running your token server locally: Use a tunneling service like ngrok to expose it: 
ngrok http 8888
# Use the generated https:// URL as your token endpoint
Your agent can run on your local machine without any tunneling—it just connects outbound to the LiveKit server like any other client.