Skip to main content

​
Overview

The LiveKit integration enables real-time monitoring of voice communications built on the LiveKit platform. Stream call data directly to Roark for analysis, evaluation, and quality monitoring.

​
Prerequisites

Before setting up the integration, ensure you have:
  • A LiveKit Cloud account or self-hosted LiveKit server
  • LiveKit API credentials (API Key and Secret)
  • Admin access to configure webhooks in LiveKit

​
Setup Instructions

​
Step 1: Create Integration

  1. Navigate to Settings → Integrations in your Roark dashboard
  2. Click Add Integration and select LiveKit
  3. Enter the following configuration:
FieldDescriptionExample
Integration NameFriendly name for this integrationProduction LiveKit
Server URLYour LiveKit WebSocket URLwss://example.livekit.cloud
API KeyLiveKit API keyAPIxxxxxxxxxxxxx
API SecretLiveKit API secretKeep this secure

​
Step 2: Configure Webhook

After creating the integration, Roark provides a webhook URL:
  1. Copy the webhook URL from the integration settings
  2. Navigate to your LiveKit dashboard
  3. Go to Settings → Webhooks
  4. Add the Roark webhook URL
  5. Select the following events:
    • room_started
    • room_finished
    • participant_joined
    • egress_ended

​
Step 3: Configure Agents

Under the Agents section of the integration, decide how LiveKit calls map to Roark agents:
  • Import named LiveKit agents — Roark fetches the named agents configured in your LiveKit project so you can choose which ones to track. Each imported agent becomes its own Roark agent, and calls are routed based on the LiveKit agent name that participated in the room.
  • Assign all calls to a single Roark agent — Pick one Roark agent and every call from this integration is attributed to it. Use this when you rely on LiveKit’s automatic dispatch (unnamed agents) or when you don’t care about distinguishing multiple agents.
You can switch between these modes later, but existing calls will keep the agent attribution they had at ingest time.

​
Step 4: WebRTC Endpoints (optional)

The WebRTC section of the integration page is where you manage all LiveKit WebRTC endpoints for this integration. On first setup it can auto-create one endpoint per imported agent so you can start running simulations immediately; after the integration exists you can come back to this same section at any time to add, edit, or remove endpoints. See WebRTC Endpoints below for the full list of settings — you can skip this step and add endpoints later if you prefer.

​
Step 5: Select Evaluators

Choose which evaluators to apply to LiveKit calls:
  • All Evaluators - Apply every available evaluator
  • Selected Evaluators - Choose specific evaluators for this integration

​
Step 6: Activate Integration

Toggle the integration status to Active to begin receiving call data.

​
WebRTC Endpoints

Roark can run simulations directly over WebRTC against a LiveKit room instead of placing a phone call. This is the recommended path for LiveKit agents because it avoids SIP trunking and exercises the exact transport your production users connect over.

​
Managing WebRTC Endpoints

All LiveKit WebRTC endpoints for an integration are managed from the WebRTC section of the integration page:
  1. Go to Settings → Integrations and open your LiveKit integration.
  2. Expand the WebRTC section to see every endpoint attached to an agent that belongs to this integration. Each row shows the agent name and environment.
  3. Click an existing endpoint to edit it, or click Add WebRTC endpoint to create a new one. The add flow opens the same editor used on the agent page and is scoped to agents managed by this integration.
On initial integration setup, Roark can also auto-create one WebRTC endpoint per imported agent in a single step — see Step 4: WebRTC Endpoints above. After the integration exists, use the flow described here for every change.

​
Room Management Mode

When configuring the endpoint you pick who is responsible for creating the LiveKit room that a simulation runs in.
Roark creates the room in your LiveKit project at the start of each simulation using the API credentials from the integration, then joins the room as the simulated caller.
  • Agent dispatch — If a Named LiveKit Agent is set on the integration, Roark explicitly dispatches that agent into the room so it joins as soon as the room is created. If no named agent is set, Roark relies on LiveKit’s automatic dispatch behavior — any unnamed worker connected to your LiveKit project will pick up the room automatically.
  • Room metadata — Optionally provide a JSON string that Roark attaches to the room it creates. Use this to pass context to your agent (for example, a customer ID, scenario tag, or feature flag) that your worker can read from the room metadata on join.
This mode is the easiest to set up and works for most agents that use LiveKit’s standard dispatch model.
Once the endpoint exists, use it like any other agent endpoint when building run plans and running simulations.

​
What Gets Synced

LiveKit integrations sync the following data:
  • Call Events - Room creation, participant joining, call completion
  • Recording Files - MP4 recordings from egress events
  • Call Metadata - Duration, participant count, room configuration
  • Transcripts - When speech-to-text is enabled
  • Named Agents - When agent import is enabled in the Agents step, the list of named LiveKit agents from your project
LiveKit does not sync agent prompts or worker source code, as it’s a real-time communication platform rather than an AI agent provider. Only agent names are imported so Roark can attribute calls to the correct agent.

​
Webhook Events

The integration processes these LiveKit events:
EventDescriptionRoark Action
room_startedRoom createdInitialize call record
room_finishedRoom endedFinalize call, trigger evaluation
participant_joinedUser joinedUpdate participant list
egress_endedRecording readyProcess recording file

​
Call Sampling & Metadata Filtering

Roark provides two ways to control which LiveKit calls are processed:

​
Random Sampling

Set a sampling rate (0–100%) in the integration settings to randomly sample a percentage of calls. This is useful when you want to evaluate a representative subset without any code changes.

​
Metadata Filtering (Per-Call Control)

For more granular control, set roark.skip to true in your LiveKit room metadata to tell Roark to skip processing for specific calls. 
from livekit import api

room = api.CreateRoomRequest(
    name="my-room",
    metadata='{"roark.skip": true}'
)
How it works:
  • Calls without roark.skip in metadata are processed normally (safe default)
  • Calls with roark.skip set to true are skipped entirely — no recording, no evaluation, no processing
  • The check happens at the webhook level, so skipped calls use zero Roark resources
  • You can combine metadata filtering with sampling — sampling is applied first, then metadata filtering
Metadata filtering is ideal when you want deterministic control over which calls are processed, such as skipping internal test calls or only evaluating calls for specific customers.

​
Monitoring Integration Health

Check your integration status in the Roark dashboard:
  • Active 🟢 - Receiving and processing events
  • Inactive 🔴 - Integration paused
  • Error ⚠️ - Configuration or connection issues
View recent webhook deliveries and any error messages in the integration details.

​
Next Steps

Enable Tracing

Send OpenTelemetry traces from your LiveKit agent

Configure Evaluators

Set up evaluation criteria

View Live Calls

Monitor calls in real-time

Integration Overview

Learn about all integrations