Vanilla JS Frontend SDK

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

​

Methods

​

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:

​

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).

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.