React Frontend SDK

​

useLayercodeAgent Hook

import { useEffect } from "react";
import { useLayercodeAgent } from "@layercode/react-sdk";

// Connect to a Layercode agent
const {
  // Methods
  connect,
  disconnect,
  triggerUserTurnStarted,
  triggerUserTurnFinished,
  sendClientResponseText,
  sendClientResponseData,
  setAudioInput,

  // State
  status,
  audioInput,
  userAudioAmplitude,
  agentAudioAmplitude,
} = useLayercodeAgent({
  agentId: "your-agent-id",
  authorizeSessionEndpoint: "/api/authorize",
  conversationId: "optional-conversation-id", // optional
  metadata: { userId: "user-123" }, // optional
  onAudioInputChanged: (enabled) => {
    console.log("Microphone enabled?", enabled);
  },
  onAgentSpeakingChange: (isSpeaking) => console.log("Agent speaking:", isSpeaking),
  onUserSpeakingChange: (isSpeaking) => console.log("User speaking:", isSpeaking),
  onConnect: ({ conversationId, config }) => {
    console.log("Connected to agent", conversationId);
    console.log("Agent config", config);
  },
  onDisconnect: () => console.log("Disconnected from agent"),
  onError: (error) => console.error("Agent error:", error),
  onDataMessage: (data) => console.log("Received data:", data),
});

useEffect(() => {
  connect();

  return () => {
    disconnect();
  };
}, [connect, disconnect]);

​

Hook Options

​

Return Values

​

State

​

Turn-taking (Push-to-Talk)

​

Audio Input Controls

​

Agent Audio Output Controls

Need to hide agent audio temporarily (for example, when playing other media in your UI)? Toggle setAudioOutput(false) while the session stays active, and re-enable with setAudioOutput(true) once you want to hear the agent again. Combine this with the audioOutput state or the onAudioOutputChanged callback to drive your UI controls.

​

Audio / Mic Controls

​

Text messages

​

Notes & Best Practices

• The hook manages microphone access, audio streaming, and playback automatically.
• Start text-first experiences with audioInput: false and call setAudioInput(true) when the user explicitly opts into voice. Pair this with enableAmplitudeMonitoring: false to skip microphone metering until voice is enabled.
• The metadata option allows you to set custom data which is then passed to your backend webhooks for this session (useful for user/session tracking).
• The conversationId can be used to resume a previous conversation, or omitted to start a new one. The hook will report null until it connects.

​

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 { useMemo } from "react";
import { useLayercodeAgent } from "@layercode/react-sdk";

export function AgentWidget() {
  const authorizeSessionRequest = useMemo(
    () => 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;
    },
    [],
  );

  const { connect, disconnect, status } = useLayercodeAgent({
    agentId: "agent_123",
    authorizeSessionEndpoint: "https://example.com/authorize-session",
    authorizeSessionRequest,
  });

  // .. Render your voice agent here
}

​

Request payload

• agent_id – ID of the agent to connect.
• metadata – metadata supplied when creating the hook.
• sdk_version – version string of the React SDK (for example, "2.2.1").
• conversation_id – present only when reconnecting to an existing conversation.

​

Response payload

{
  "client_session_key": "cs_abc123",
  "conversation_id": "conv_456"
}

​

Troubleshooting

​

AudioWorklet InvalidStateError on first connect

• Trigger the first connect() from a user gesture—e.g., a “Start voice agent” button that awaits connect().
• Keep disconnect() inside an effect cleanup so teardown still runs automatically.
• Expect the issue mostly during rapid development reloads or in React Strict Mode, where components mount twice. In production, users typically gesture before launching the agent, so reconnects after the initial gesture are safe.