import LayercodeClient from "https://cdn.jsdelivr.net/npm/@layercode/js-sdk@latest/dist/layercode-js-sdk.esm.js";

window.layercode = new LayercodeClient({
  pipelineId: "your-pipeline-id",
  sessionId: "your-session-id", // optional
  authorizeSessionEndpoint: "/api/authorize",
  metadata: { userId: "123" }, // optional
  onConnect: ({ sessionId }) => console.log("connected", sessionId),
  onDisconnect: () => console.log("disconnected"),
  onError: (err) => console.error("error", err),
  onDataMessage: (msg) => console.log("data message", msg),
  onUserAmplitudeChange: (amp) => console.log("user amplitude", amp),
  onAgentAmplitudeChange: (amp) => console.log("agent amplitude", amp),
  onStatusChange: (status) => console.log("status", status),
});

window.layercode.connect();
layercode-js-sdk.

​
LayercodeClient

The LayercodeClient is the core client for all JavaScript frontend SDKs, providing audio recording, playback, and real-time communication with the Layercode pipeline. 
import LayercodeClient from "https://cdn.jsdelivr.net/npm/@layercode/js-sdk@latest/dist/layercode-js-sdk.esm.js";

window.layercode = new LayercodeClient({
  pipelineId: "your-pipeline-id",
  sessionId: "your-session-id", // optional
  authorizeSessionEndpoint: "/api/authorize",
  metadata: { userId: "123" }, // optional
  onConnect: ({ sessionId }) => console.log("connected", sessionId),
  onDisconnect: () => console.log("disconnected"),
  onError: (err) => console.error("error", err),
  onDataMessage: (msg) => console.log("data message", msg),
  onUserAmplitudeChange: (amp) => console.log("user amplitude", amp),
  onAgentAmplitudeChange: (amp) => console.log("agent amplitude", amp),
  onStatusChange: (status) => console.log("status", status),
});

window.layercode.connect();

​
Usage Example

​
Constructor Options

​
options
object
required
Options for the LayercodeClient.
​
options.pipelineId
string
required
The ID of your Layercode pipeline.
​
options.sessionId
string
The session ID to resume a previous session (optional).
​
options.authorizeSessionEndpoint
string
required
The endpoint to authorize the session (should return a client_session_key and session_id).
​
options.metadata
object
Optional metadata to send with the session authorization request.
​
options.onConnect
function
Callback when the client connects. Receives an object: { sessionId: string | null }.
​
options.onDisconnect
function
Callback when the client disconnects.
​
options.onError
function
Callback when an error occurs. Receives an Error object.
​
options.onDataMessage
function
Callback for custom data messages from the server.
​
options.onUserAmplitudeChange
function
Callback for changes in the user’s microphone amplitude (number, 0-1).
​
options.onAgentAmplitudeChange
function
Callback for changes in the agent’s audio amplitude (number, 0-1).
​
options.onStatusChange
function
Callback when the client’s status changes. Receives a string: "disconnected" | "connecting" | "connected" | "error".

​
Methods

​
connect
function
required
connect(): Promise<void> Connects to the Layercode pipeline, authorizes the session, and starts audio capture and playback.
​
disconnect
function
required
disconnect(): Promise<void> Disconnects from the Layercode pipeline, stops audio capture and playback, and closes the WebSocket.

​
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:
​
triggerUserTurnStarted
function
triggerUserTurnStarted(): Promise<void> Signals that the user has started speaking (for push-to-talk mode). Interrupts any agent audio playback.
​
triggerUserTurnFinished
function
triggerUserTurnFinished(): Promise<void> Signals that the user has finished speaking (for push-to-talk mode).

​
Events & Callbacks

  • onConnect: Called when the connection is established. Receives { sessionId }.
  • onDisconnect: Called when the connection is closed.
  • onError: Called on any error (authorization, WebSocket, audio, etc).
  • onDataMessage: Called when a custom data message is received from the server (see response.data events from your backend).
  • onUserAmplitudeChange: Called with the user’s microphone amplitude (0-1).
  • onAgentAmplitudeChange: Called with the agent’s audio amplitude (0-1).
  • onStatusChange: Called when the status changes ("disconnected", "connecting", "connected", "error").

​
Notes & Best Practices

  • The SDK 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).
If your backend is on a different domain, set authorizeSessionEndpoint to the full URL (e.g., https://your-backend.com/api/authorize).
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.