React Frontend SDK

layercode-react-sdk.

​

useLayercodePipeline Hook

The useLayercodePipeline hook provides a simple way to connect your React app to a Layercode pipeline, handling audio streaming, playback, and real-time communication.

import { useLayercodePipeline } from "@layercode/react";

// Connect to a Layercode pipeline
const {
  // Methods
  triggerUserTurnStarted,
  triggerUserTurnFinished,

  // State
  status,
  userAudioAmplitude,
  agentAudioAmplitude,
} = useLayercodePipeline({
  pipelineId: "your-pipeline-id",
  authorizeSessionEndpoint: "/api/authorize",
  sessionId: "optional-session-id", // optional
  metadata: { userId: "user-123" }, // optional
  onConnect: ({ sessionId }) => console.log("Connected to pipeline", sessionId),
  onDisconnect: () => console.log("Disconnected from pipeline"),
  onError: (error) => console.error("Pipeline error:", error),
  onDataMessage: (data) => console.log("Received data:", data),
});

​

Hook Options

​

Return Values

The useLayercodePipeline hook returns an object with the following properties:

​

State

​

Turn-taking (Push-to-Talk)

Layercode supports both automatic and push-to-talk turn-taking. For push-to-talk, use these methods to signal when the user starts and stops speaking:

​

Notes & Best Practices

• The hook manages microphone access, audio streaming, and playback automatically.
• The metadata option allows you to set custom data which is then passed to your backend webhook (useful for user/session tracking).
• The sessionId can be used to resume a previous session, or omitted to start a new one.

​

Authorizing Sessions

To connect a client (browser) to your Layercode voice pipeline, you must first authorize the session. The SDK will automatically send a POST request to the path (or url if your backend is on a different domain) passed in the authorizeSessionEndpoint option. In this endpoint, you will need to call the Layercode REST API to generate a client_session_key and session_id (if it’s a new session).

Why is this required? Your Layercode API key should never be exposed to the frontend. Instead, your backend acts as a secure proxy: it receives the frontend’s request, then calls the Layercode authorization API using your secret API key, and finally returns the client_session_key to the frontend.

This also allows you to authenticate your user, and set any additional metadata that you want passed to your backend webhook.

How it works:

1. Frontend: The SDK automatically sends a POST request to your authorizeSessionEndpoint with a request body.

2. Your Backend: Your backend receives this request, then makes a POST request to the Layercode REST API /v1/pipelines/authorize_session endpoint, including your LAYERCODE_API_KEY as a Bearer token in the headers.

3. Layercode: Layercode responds with a client_session_key (and a session_id), which your backend returns to the frontend.

4. Frontend: The SDK uses the client_session_key to establish a secure WebSocket connection to Layercode.

Example backend authorization endpoint code:

export const dynamic = "force-dynamic";
import { NextResponse } from "next/server";

export const POST = async (request: Request) => {
  // Here you could do any user authorization checks you need for your app
  const endpoint = "https://api.layercode.com/v1/pipelines/authorize_session";
  const apiKey = process.env.LAYERCODE_API_KEY;
  if (!apiKey) {
    throw new Error("LAYERCODE_API_KEY is not set.");
  }
  const requestBody = await request.json();
  if (!requestBody || !requestBody.pipeline_id) {
    throw new Error("Missing pipeline_id in request body.");
  }
  try {
    const response = await fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      body: JSON.stringify(requestBody),
    });
    if (!response.ok) {
      const text = await response.text();
      throw new Error(text || response.statusText);
    }
    return NextResponse.json(await response.json());
  } catch (error: any) {
    console.log("Layercode authorize session response error:", error.message);
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
};

For a Python backend example see the FastAPI backend guide.