Using your own Livekit Instance

This guide explains how to integrate the HeyGen Streaming API with your own self-hosted or cloud-managed LiveKit instance. This approach gives you granular control over your WebRTC infrastructure, session management, and participant permissions.

In this flow, you are responsible for generating all necessary LiveKit tokens. When you call the HeyGen API, you will pass a livekit_settings object containing the details of your instance and a pre-generated token for the HeyGen avatar to use.

When to Use This Flow

This advanced integration path is recommended for developers with specific infrastructure or application requirements. Choose this flow if your project involves:

Enterprise Security and Compliance: Ideal for enterprise customers who need to run all traffic through their own hardened and monitored LiveKit infrastructure to meet strict security, data residency, or compliance policies.
Existing LiveKit Solutions: If your application is already built on a LiveKit-based video stack, this method allows you to seamlessly integrate HeyGen avatars into your existing rooms and workflows without disrupting your architecture.
Complex or Multiple Agent Scenarios: When your session requires multiple agents (e.g., a conversational agent, a moderator bot, and a recording service), managing your own LiveKit instance provides the granular control needed to issue tokens with custom permissions for each participant.
Tricky Agent Orchestration: For sophisticated flows where agents need to dynamically enter or leave rooms, pass custom metadata, or manage complex interactions using LiveKit's data channels, this approach provides the necessary flexibility that a managed solution might not offer.

Token Generation Requirements

Since you are managing the LiveKit instance, your backend is responsible for generating all access tokens. A typical session requires at least two distinct tokens with specific permissions:

HeyGen Avatar Token:
This token is for the HeyGen Media Server to join your room. You generate this token on your backend before calling the HeyGen API and pass it inside the livekit_settings.token field.
- Identity: Must be unique for the HeyGen avatar (e.g., heygen-avatar-session123).
- Required Permissions:
  - canPublish: true (to stream video and audio into the room).
  - canSubscribe: true (to receive audio from other participants, like the user or an agent).
  - canPublishData: true (for session metadata and events).
Client (User) Token:
This token is for your front-end application user. Your backend generates this and passes it to your client, which then uses it to connect to your LiveKit room.
- Identity: Must be unique to the user (e.g., user-abc-456).
- Required Permissions:
  - canPublish: true (to send their microphone audio).
  - canSubscribe: true (to see and hear the HeyGen avatar).

Workflow

In this model, your backend application is the central orchestrator for generating tokens and initiating the session.

The process begins on your backend (e.g., in response to a client request to start a new session).
Your backend server generates a HeyGen Avatar Token with the necessary permissions as described above.
Your backend calls the HeyGen /v1/streaming.new endpoint and includes the livekit_settings object containing:
- url: The WebSocket URL of your LiveKit server (e.g., wss://my-livekit.my-domain.com).
- room: The name of the room the avatar should join.
- token: The HeyGen Avatar Token you generated in the previous step.
The HeyGen API receives the request and, in the background, uses your token to connect its Media Server (the avatar) to your LiveKit room.
The HeyGen API responds with a session_id. Note: The response will not contain access_token or livekit_agent_token, as you are managing all tokens.
Separately, your backend generates a Client (User) Token and passes it, along with your LiveKit URL and room name, to your front-end client.
Your client application uses these details to connect to your LiveKit room, where it can now interact with the HeyGen avatar.