Skip to main content
To integrate Lyzr’s low-latency voice AI into a third-party client, you will follow a four-step lifecycle: starting a session via REST API, connecting to a real-time room via WebRTC (LiveKit), streaming audio, and terminating the session.

​
1. Authentication & Configuration

All requests to the Lyzr Voice API require an x-api-key header containing your organization’s API key.
  • Base URL: https://ba-dc3c74596474493fba4d44a9ea25b57f.ecs.us-east-1.on.aws
  • Authentication Header: x-api-key: <YOUR_LYZR_API_KEY>

​
2. The Integration Flow

​
Step 1: Start a Session

Before connecting via WebRTC, you must request a session token from the Lyzr backend. This “dispatches” the agent to a specific room.
  • Endpoint: POST /v1/sessions/start
  • Request Body: 
    {
  "userIdentity": "unique-user-id",
  "agentId": "your-agent-id",
  "agentConfig": { /* Optional overrides for prompt/engine */ }
}
  • Response: You will receive a userToken and a livekitUrl.

​
Step 2: Connect to the Agent Room

Lyzr uses the LiveKit SDK for real-time audio transport. Use the userToken and livekitUrl from the previous step to join the room. In a React environment, you can use the <LiveKitRoom> component: 
<LiveKitRoom
  serverUrl={sessionData.livekitUrl}
  token={sessionData.userToken}
  connect={true}
  audio={true}
>
  <RoomAudioRenderer />
  <BackgroundAudioRenderer /> {/* Essential for Lyzr ambient SFX */}
</LiveKitRoom>

​
Step 3: Stream Audio & Handle Events

Once connected, publish your microphone track. The agent will automatically respond with audio and transcription data events.
  • Audio Output: Use the standard LiveKit RoomAudioRenderer for the agent’s voice.
  • Background Audio: Lyzr agents often publish a secondary track named background_audio for ambient sounds and “thinking” sound effects. You must manually attach this track to an HTML audio element.
  • Transcriptions: Use the useTrackTranscription hook to display real-time captions for both the user and the agent.

​
Step 4: End the Session

To prevent unnecessary costs and clean up resources, explicitly end the session when the user hangs up.
  • Endpoint: POST /v1/sessions/end
  • Body: { "roomName": "room-id-from-start-response" }

​
3. Reference Implementation

​
API Client (src/lib/api-client.ts)

The demo uses a centralized apiFetch wrapper to inject the API key and handle prefixes: 
export async function apiFetch<T>(endpoint: string, init?: RequestInit): Promise<T> {
    const config = getApiConfig();
    return fetch(`${config.serverUrl}/v1${endpoint}`, {
        ...init,
        headers: {
            'Content-Type': 'application/json',
            'x-api-key': config.apiKey,
            ...init?.headers,
        },
    }).then(res => res.json());
}

​
Session Hook (src/hooks/useLyzrSession.ts)

This hook manages the state transition from idle to connected: 
export function useLyzrSession() {
    const [state, setState] = useState('idle');
    const [sessionData, setSessionData] = useState(null);

    const connect = async (agentId) => {
        setState('connecting');
        const data = await startSession({ agentId }); // Calls /v1/sessions/start
        setSessionData(data);
        setState('connected');
    };

    const disconnect = async () => {
        if (sessionData) await endSession(sessionData.roomName);
        setState('idle');
    };

    return { state, sessionData, connect, disconnect };
}