Vanilla JS Frontend SDK

​

LayercodeClient

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

window.layercode = new LayercodeClient({
  agentId: "your-agent-id",
  conversationId: "your-conversation-id", // optional
  authorizeSessionEndpoint: "/api/authorize",
  metadata: { userId: "123" }, // optional

  // Connection lifecycle
  onConnect: ({ conversationId, config }) => {
    console.log("connected", conversationId);
    console.log("agent config", config);
  },
  onDisconnect: () => console.log("disconnected"),
  onError: (err) => console.error("error", err),
  onStatusChange: (status) => console.log("status", status),

  // Messaging & events
  onMessage: (msg) => console.log("message", msg),           // non-audio messages
  onDataMessage: (msg) => console.log("data message", msg),  // response.data messages

  // Audio meters & speaking state
  onUserAmplitudeChange: (amp) => console.log("user amplitude", amp),
  onAgentAmplitudeChange: (amp) => console.log("agent amplitude", amp),
  audioInputChanged: (enabled) => console.log("mic enabled", enabled),
  onUserIsSpeakingChange: (speaking) => console.log("user speaking?", speaking),
  onAgentSpeakingChange: (speaking) => console.log("agent speaking?", speaking),

  // Device & mute state
  onDeviceSwitched: (id) => console.log("active input device", id),
  onDevicesChanged: (list) => console.log("devices changed", list),
  onMuteStateChange: (muted) => console.log("muted?", muted),

  enableAmplitudeMonitoring: false, // skip metering while audio is disabled
});

window.layercode.connect();

​

Usage Example

​

Constructor Options

​

Methods

Tip: Call setAudioOutput(false) to silence agent audio while another clip plays in your UI, then restore playback with setAudioOutput(true) when you’re ready. Pair this with the audioOutputChanged callback to keep toggles in sync.

​

Turn-taking (Push-to-Talk)

​

Text messages

​

Events & Callbacks

​

Properties

​

Agent Config (from authorizeSessionEndpoint)

type AgentConfig = {
  transcription: {
    trigger: 'push_to_talk' | 'automatic';
    can_interrupt: boolean;
  };
  vad?: {
    enabled?: boolean;
    gate_audio?: boolean;            // default: true
    buffer_frames?: number;          // default: 10
    model?: string;                  // default: 'v5'
    positive_speech_threshold?: number; // default: 0.15
    negative_speech_threshold?: number; // default: 0.05
    redemption_frames?: number;      // default: 4
    min_speech_frames?: number;      // default: 2
    pre_speech_pad_frames?: number;  // default: 0
    frame_samples?: number;          // default: 512
  };
};

​

Notes & Best Practices

• The SDK manages microphone access, audio streaming, and playback automatically.
• Use audioInput: false plus setAudioInput(true) to defer the browser permission prompt until the user explicitly switches to voice. Disable amplitude monitoring at the same time to avoid unnecessary processing.
• The metadata option allows you to set custom data which is then passed to your backend webhook (useful for user/session tracking).
• The conversationId can be used to resume a previous conversation, or omitted to start a new one.

​

Small device example

await layercode.setInputDevice('default');
const devices = await layercode.listDevices();
const usb = devices.find(d => /USB/i.test(d.label));
if (usb) await layercode.setInputDevice(usb.deviceId);

​

Authorizing Sessions

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/agents/web/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 conversation_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.

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/agents/web/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.agent_id) {
    throw new Error("Missing agent_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 });
  }
};

​

Custom Authorization

import LayercodeClient from "@layercode/js-sdk";

const client = new LayercodeClient({
  agentId: "agent_123",
  authorizeSessionEndpoint: "/api/authorize",
  authorizeSessionRequest: async ({ url, body }) => {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Custom-Header": "my-header",
      },
      body: JSON.stringify(body),
    });

    if (!response.ok) {
      throw new Error(`Authorization failed: ${response.statusText}`);
    }

    return response;
  },
});

​

Request payload

• agent_id – ID of the agent to connect.
• metadata – metadata supplied when instantiating the client.
• sdk_version – version string of the JavaScript SDK.
• conversation_id – present only when reconnecting to an existing conversation.

​

Troubleshooting

​

AudioWorklet InvalidStateError on first connect

• Gate the first connect() behind a user gesture (click, tap, key press)—for example, a “Start voice agent” button.
• Await connect() inside that handler; keep any teardown logic (like disconnect()) in lifecycle cleanup.
• Expect this to show up most during rapid local reloads or with React Strict Mode double-mounting. In real usage, the user normally clicks before the agent activates, so reconnects after the first gesture are safe.