Drıftstack docs
Docs

Live video for agent sessions

Live video is delivered through Driftstack’s own video relay (open-source LiveKit server software), a WebRTC streaming service. When it is available on your deployment (see Pre-requisites), agent sessions publish their browser video stream into a per-session LiveKit room. Customer-side consumers (the customer dashboard, the desktop app, a third-party automation tool) subscribe to the room and render the video — typically into an <video> element.

This guide walks through the minimum-viable subscriber integration.

Pre-requisites

  • An agent session you own (created via POST /v1/agent-sessions).

  • A LiveKit-aware client. The official livekit-client package works in browsers + Node + Electron + Tauri:

    npm install livekit-client

  • Live video must be available on your deployment. The livekit field on the session-create response tells you: if it is present, you can subscribe; if it is absent, you cannot.

1. Obtain the join info

Two ways to get the LiveKit join info (ws_url, room, token, participant_identity, expires_at):

Option A — auto-populated on session-create

The simplest path. When live video is available on your deployment, POST /v1/agent-sessions returns the join info inline:

// Every agent session goes out through one of your saved proxies.
const session = await client.agentSessions.create({ proxy_id: '<proxy id>' });
if (session.livekit) {
  // ready to subscribe — go to step 2
}

session.livekit is undefined when live video has not started for the session. Clients that need a token in that state fall back to the explicit endpoint.

Option B — explicit mint

For pre-existing sessions, or when you no longer have the token from create:

const livekit = await fetch(
  `https://api.driftstack.dev/v1/agent-sessions/${sessionId}/livekit-token`,
  {
    method: 'POST',
    headers: { authorization: `Bearer ${apiKey}` },
  },
).then((r) => r.json());

Errors:

  • 404 — session unknown or cross-account (anti-enumeration)
  • 403 — session is closed (not currently subscribable)
  • 503 — live video is not available right now; contact support if it persists

2. Connect to the room

Construct a Room and call connect():

import { Room, RoomEvent } from 'livekit-client';

const room = new Room({
  adaptiveStream: true,
  dynacast: true,
});

room.on(RoomEvent.TrackSubscribed, (track) => {
  if (track.kind === 'video') {
    const el = document.querySelector<HTMLVideoElement>('video#live')!;
    track.attach(el);
  }
});

await room.connect(livekit.ws_url, livekit.token);
// You're now subscribed; video frames stream into the <video> element.

adaptiveStream + dynacast are recommended — they let LiveKit send a lower resolution when the viewer’s bandwidth is limited.

3. Disconnect on unmount

Browser pages should disconnect explicitly:

window.addEventListener('beforeunload', () => {
  void room.disconnect();
});

In React, do it in the useEffect cleanup:

useEffect(() => {
  const room = new Room({ adaptiveStream: true, dynacast: true });
  // … wire events, connect …
  return () => {
    void room.disconnect();
  };
}, [livekit]);

Token lifetime + reconnect

Tokens are valid for 24 hours and are only checked when you connect. That is longer than a session runs (a session is closed about 12 hours after it was created, at the latest), so one token normally lasts the whole session. If you lost the token, or need to join a running session from another client, mint a fresh token via the explicit endpoint (Option B above).

The livekit-client library handles transient drops + auto- reconnect internally with the token it already has.

SDK helpers

You do not have to hand-write the HTTP calls above. Each SDK wraps them:

Step TypeScript Python Go
Create a session (join info comes back in livekit) client.agentSessions.create({ proxy_id }) client.agent_sessions.create({"proxy_id": ...}) client.AgentSessions.Create(ctx, body, nil)
Mint a fresh token for a running session client.agentSessions.livekitToken(id) client.agent_sessions.livekit_token(id) client.AgentSessions.LivekitToken(ctx, id)

Connecting to the room and attaching the video track is done with the livekit-client library exactly as in steps 2–3; the Driftstack desktop app uses the same calls.

See also