React SDK

Installation

Installera paketet i ditt projekt via en pakethanterare.

npm install @elevenlabs/react
# or
yarn add @elevenlabs/react
# or
pnpm install @elevenlabs/react

Användning

Här är ett minimalt fungerande exempel som ansluter till en agent och låter användaren starta och avsluta en röstkonversation:

import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from "@elevenlabs/react";
function App() {
  return (
    <ConversationProvider>
      <Agent />
    </ConversationProvider>
  );
}
function Agent() {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();
  if (status === "connected") {
    return <button onClick={endSession}>End</button>;
  }
  return (
    <button onClick={() => startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6" })}>
      Start
    </button>
  );
}

Avsnitten nedan förklarar varje del i detalj.

ConversationProvider

Alla konversations-hooks måste användas i en ConversationProvider. Omslut din app (eller relevant delträd) med denna provider.

import { ConversationProvider } from "@elevenlabs/react";
function App() {
  return (
    <ConversationProvider>
      <YourComponents />
    </ConversationProvider>
  );
}

Provider-props

Providern accepterar samma alternativ som useConversation — inklusive callbacks, klientverktyg, åsidosättningar och serverplats — så att du kan konfigurera dem på provider-nivå i stället för i varje hook-konsument.

<ConversationProvider
  onConnect={() => console.log("Connected")}
  onDisconnect={() => console.log("Disconnected")}
  onError={(error) => console.error("Error:", error)}
  clientTools={{
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);
      return "Message displayed";
    },
  }}
  serverLocation="eu-residency"
>
  <YourComponents />
</ConversationProvider>

Kontrollerad avstängningsstatus

Providern stöder propsen isMuted och onMutedChange för hantering av kontrollerad avstängningsstatus, så att du kan spara avstängningsstatus externt (t.ex. mellan sessioner).

const [muted, setMuted] = useState(false);
<ConversationProvider isMuted={muted} onMutedChange={setMuted}>
  <YourComponents />
</ConversationProvider>;

useConversation

En praktisk React-hook som kombinerar alla detaljerade hooks till ett enda returvärde. Kräver en överordnad ConversationProvider.

Initiera konversation

import { useConversation } from "@elevenlabs/react";
function MyComponent() {
  const conversation = useConversation();
  // ...
}

Observera att ElevenAgents kräver mikrofonåtkomst för röstkonversationer. Överväg att förklara detta och bevilja åtkomst i appens gränssnitt innan konversationen startar.

// call after explaining to the user why the microphone access is needed
await navigator.mediaDevices.getUserMedia({ audio: true });

Alternativ

Hooken kan valfritt initieras med alternativ. De kan också skickas på ConversationProvider-nivå.

const conversation = useConversation({
  /* options object */
});

Alternativen omfattar:

• clientTools - objektdefinition för klientverktyg som kan anropas av agenten. Se nedan för mer information.
• overrides - objektdefinition för åsidosättningar av konversationsinställningar. Se nedan för mer information.
• textOnly - om konversationen ska köras i läget endast text. Se nedan för mer information.
• serverLocation - anger serverplatsen ("us", "eu-residency", "in-residency", "global"). Standardvärdet är "us".

Översikt över callbacks

• onConnect - hanterare som anropas när konversationsanslutningen har upprättats.
• onDisconnect - hanterare som anropas när konversationsanslutningen avslutas.
• onMessage - hanterare som anropas när ett nytt meddelande tas emot. Det kan vara preliminära eller slutliga transkriberingar av användarens röst, svar från LLM eller felsökningsmeddelanden när ett felsökningsalternativ är aktiverat.
• onError - hanterare som anropas när ett fel uppstår.
• onAudio - hanterare som anropas när ljuddata tas emot.
• onModeChange - hanterare som anropas när konversationsläget ändras (talar/lyssnar).
• onStatusChange - hanterare som anropas när anslutningsstatusen ändras.
• onCanSendFeedbackChange - hanterare som anropas när möjligheten att skicka feedback ändras.
• onDebug - hanterare som anropas när felsökningsinformation är tillgänglig.
• onUnhandledClientToolCall - hanterare som anropas när ett ohanterat anrop av ett klientverktyg påträffas.
• onVadScore - hanterare som anropas när poängen för röstaktivitetsdetektering ändras.
• onAudioAlignment - hanterare som anropas när ljudjusteringsdata tas emot och ger tidsinformation på teckennivå för agentens tal.
• onAgentChatResponsePart - hanterare som anropas med agentens svarstext när den genereras, som start-, delta- och stopphändelser. Skickas alltid i läget endast text. För röstkonversationer aktiverar du agent_chat_response_part i agentens client_events-konfiguration.

Klientverktyg

Klientverktyg gör det möjligt för agenten att anropa funktionalitet på klientsidan. De kan användas för att utlösa åtgärder i klienten, som att öppna en modal eller göra ett API-anrop åt användaren.

Definitionen av klientverktyg är ett objekt med funktioner och måste vara identisk med din konfiguration i ElevenLabs UI, där du kan namnge och beskriva olika verktyg samt konfigurera parametrarna som skickas av agenten.

const conversation = useConversation({
  clientTools: {
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);
      return "Message displayed";
    },
  },
});

Om funktionen returnerar ett värde skickas det tillbaka till agenten som ett svar.

Verktyget måste uttryckligen ställas in för att blockera konversationen i ElevenLabs UI så att agenten kan invänta och reagera på svaret. Annars förutsätter agenten att åtgärden lyckades och fortsätter konversationen.

Åsidosättningar av konversationer

Du kan välja att åsidosätta olika inställningar för konversationen och ange dem dynamiskt baserat på andra användarinteraktioner.

Vi stöder åsidosättning av olika inställningar. Dessa inställningar är valfria och kan användas för att anpassa konversationsupplevelsen.

Följande inställningar är tillgängliga:

const conversation = useConversation({
  overrides: {
    agent: {
      prompt: {
        prompt: "My custom prompt",
      },
      firstMessage: "My custom first message",
      language: "en",
    },
    tts: {
      voiceId: "custom voice id",
    },
    conversation: {
      textOnly: true,
    },
  },
});

Endast text

Om din agent är konfigurerad för att köras i läget endast text, dvs. inte skickar eller tar emot ljudmeddelanden, kan du använda denna flagga för att använda en lättare version av konversationen. I så fall ombeds användaren inte om mikrofonbehörighet och inget ljudkontext skapas.

const conversation = useConversation({
  textOnly: true,
});

Kontrollerad status

Du kan styra vissa delar av konversationsstatusen direkt via hook-alternativen:

const [micMuted, setMicMuted] = useState(false);
const conversation = useConversation({
  micMuted,
  // ... other options
});
// Update controlled state
setMicMuted(true); // This will automatically mute the microphone

Dataresidens

Du kan ange vilken ElevenLabs-serverregion som ska anslutas till. Mer information finns i guiden för dataresidens.

const conversation = useConversation({
  serverLocation: "eu-residency", // or "us", "in-residency", "global"
});

Metoder

startSession

Metoden startSession upprättar anslutningen och börjar använda mikrofonen för att kommunicera med ElevenLabs Agents-agenten. Metoden accepterar ett alternativobjekt, där signedUrl, conversationToken eller agentId krävs.

Agent-ID:t kan hämtas via ElevenLabs UI.

Vi rekommenderar också att du skickar med dina egna slutanvändar-ID:n för att koppla konversationer till dina användare.

const conversation = useConversation();
// For public agents, pass in the agent ID
const conversationId = await conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  userId: "user_9302xkm82nds93", // optional field
});

För offentliga agenter (dvs. agenter utan aktiverad autentisering) krävs endast agentId.

Om konversationen kräver auktorisering använder du REST API:t för att generera signerade länkar för en WebSocket-anslutning eller en konversationstoken för en WebRTC-anslutning.

startSession returnerar ett löfte som löses till ett conversationId. Värdet är ett globalt unikt konversations-ID som du kan använda för att identifiera separata konversationer.

// Node.js server
app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
      },
    }
  );
  if (!response.ok) {
    return res.status(500).send("Failed to get signed URL");
  }
  const body = await response.json();
  res.send(body.signed_url);
});

// Client
const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();
await conversation.startSession({
  signedUrl,
});

endSession

En metod för att manuellt avsluta konversationen. Metoden kopplar från och avslutar konversationen.

await conversation.endSession();

setVolume

Ställer in konversationens utgående volym. Accepterar ett objekt med fältet volume mellan 0 och 1.

await conversation.setVolume({ volume: 0.5 });

sendUserMessage

Skickar ett textmeddelande till agenten.

Kan användas för att låta användaren skriva meddelandet i stället för att använda mikrofonen. Till skillnad från sendContextualUpdate behandlas detta som ett användarmeddelande och uppmanar agenten att ta sin tur i konversationen.

const { sendUserMessage, sendUserActivity } = useConversation();
const [value, setValue] = useState("");
return (
  <>
    <input
      value={value}
      onChange={e => {
        setValue(e.target.value);
        sendUserActivity();
      }}
    />
    <button
      onClick={() => {
        sendUserMessage(value);
        setValue("");
      }}
    >
      SEND
    </button>
  </>
);

sendContextualUpdate

Skickar kontextinformation till agenten utan att utlösa ett svar.

const { sendContextualUpdate } = useConversation();
sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);

sendFeedback

Ge feedback om konversationens kvalitet. Det hjälper till att förbättra agentens prestanda.

const { sendFeedback } = useConversation();
sendFeedback(true); // positive feedback
sendFeedback(false); // negative feedback

sendUserActivity

Meddelar agenten om användaraktivitet för att förhindra avbrott. Användbart när användaren aktivt använder appen och agenten bör pausa talet, t.ex. när användaren skriver i en chatt.

Agenten pausar talet i cirka 2 sekunder efter att ha tagit emot denna signal.

const { sendUserActivity } = useConversation();
// Call this when user is typing to prevent interruption
sendUserActivity();

changeInputDevice

Byt ljudinmatningsenhet under en aktiv röstkonversation. Denna metod är endast tillgänglig för röstkonversationer.

// Change to a specific input device
conversation.changeInputDevice({
  sampleRate: 16000,
  format: "pcm",
  preferHeadphonesForIosDevices: true,
  inputDeviceId: "a1b2c3d4e5f6", // Optional: specific device ID
});

changeOutputDevice

Byt ljudutmatningsenhet under en aktiv röstkonversation. Denna metod är endast tillgänglig för röstkonversationer.

// Change to a specific output device
conversation.changeOutputDevice({
  sampleRate: 16000,
  format: "pcm",
  outputDeviceId: "a1b2c3d4e5f6", // Optional: specific device ID
});

getId

Returnerar det aktuella konversations-ID:t.

const { getId } = useConversation();
const conversationId = getId();
console.log(conversationId); // e.g., "conv_9001k1zph3fkeh5s8xg9z90swaqa"

getInputVolume / getOutputVolume

Metoder som returnerar aktuella volymnivåer för inmatning/utmatning (skala 0–1).

const { getInputVolume, getOutputVolume } = useConversation();
const inputLevel = getInputVolume();
const outputLevel = getOutputVolume();

getInputByteFrequencyData / getOutputByteFrequencyData

Metoder som returnerar Uint8Array:er som innehåller aktuella frekvensdata för inmatning/utmatning. Se AnalyserNode.getByteFrequencyData för mer information.

const { getInputByteFrequencyData, getOutputByteFrequencyData } = useConversation();
const inputFrequencyData = getInputByteFrequencyData();
const outputFrequencyData = getOutputByteFrequencyData();

sendMCPToolApprovalResult

Skickar godkännanderesultat för MCP-verktygsanrop (Model Context Protocol).

const { sendMCPToolApprovalResult } = useConversation();
// Approve a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", true);
// Reject a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", false);

Returvärden

Utöver metoderna ovan returnerar useConversation följande reaktiva status:

• status - aktuell anslutningsstatus ("disconnected", "connecting", "connected").
• isSpeaking - om agenten talar just nu.
• isListening - om agenten lyssnar just nu.
• mode - aktuellt konversationsläge ("speaking" eller "listening").
• isMuted - om mikrofonen är avstängd just nu.
• setMuted - funktion för att stänga av/slå på mikrofonen.
• canSendFeedback - om feedback kan skickas för den aktuella konversationen.
• message - det senaste meddelandet från konversationen.

const { status, isSpeaking, isListening, isMuted, setMuted, canSendFeedback } = useConversation();
return (
  <div>
    <p>Status: {status}</p>
    <p>Agent is {isSpeaking ? 'speaking' : 'listening'}</p>
    <button onClick={() => setMuted(!isMuted)}>
      {isMuted ? 'Unmute' : 'Mute'}
    </button>
  </div>
);

Detaljerade hooks

För bättre renderingsprestanda använder du dessa hooks i stället för useConversation. Varje hook prenumererar endast på sin specifika del av statusen, så komponenter omrenderas bara när data som de använder ändras.

Alla detaljerade hooks kräver en överordnad ConversationProvider.

useConversationControls

Returnerar åtgärdsmetoder för att styra konversationen. Denna hook orsakar inga omrenderingar eftersom den endast tillhandahåller stabila funktionsreferenser.

import { useConversationControls } from "@elevenlabs/react";
function Controls() {
  const {
    startSession,
    endSession,
    sendUserMessage,
    sendContextualUpdate,
    sendUserActivity,
    setVolume,
    changeInputDevice,
    changeOutputDevice,
    sendMCPToolApprovalResult,
    getId,
    getInputVolume,
    getOutputVolume,
    getInputByteFrequencyData,
    getOutputByteFrequencyData,
  } = useConversationControls();
  return (
    <button onClick={() => startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6" })}>
      Start
    </button>
  );
}

useConversationStatus

Returnerar aktuell anslutningsstatus och ett valfritt statusmeddelande.

import { useConversationStatus } from "@elevenlabs/react";
function StatusIndicator() {
  const { status, message } = useConversationStatus();
  return <p>Status: {status}</p>; // "disconnected" | "connecting" | "connected"
}

useConversationInput

Returnerar avstängningsstatus och en setter för att slå på eller stänga av mikrofonen.

import { useConversationInput } from "@elevenlabs/react";
function MuteToggle() {
  const { isMuted, setMuted } = useConversationInput();
  return <button onClick={() => setMuted(!isMuted)}>{isMuted ? "Unmute" : "Mute"}</button>;
}

useConversationMode

Returnerar tal-/lyssningsstatus för agenten.

import { useConversationMode } from "@elevenlabs/react";
function ModeIndicator() {
  const { mode, isSpeaking, isListening } = useConversationMode();
  return <p>Agent is {isSpeaking ? "speaking" : "listening"}</p>;
}

useConversationFeedback

Returnerar feedbacktillgänglighet och en metod för att skicka feedback.

import { useConversationFeedback } from "@elevenlabs/react";
function FeedbackButtons() {
  const { canSendFeedback, sendFeedback } = useConversationFeedback();
  if (!canSendFeedback) return null;
  return (
    <div>
      <button onClick={() => sendFeedback(true)}>Like</button>
      <button onClick={() => sendFeedback(false)}>Dislike</button>
    </div>
  );
}

useRawConversation

Returnerar den råa konversationsinstansen. Detta är en reservutväg för avancerade användningsfall där du behöver direkt åtkomst till det underliggande objektet VoiceConversation eller TextConversation.

import { useRawConversation } from "@elevenlabs/react";
function Advanced() {
  const conversation = useRawConversation();
  // Access the raw conversation instance directly
}

useConversationClientTool

En hook för att dynamiskt registrera klientverktyg från React-komponenter. Verktyg avregistreras automatiskt när komponenten avmonteras.

Detta är användbart när ett verktygs hanterare behöver åtkomst till komponentstatus eller props som inte är tillgängliga på provider-nivå.

import { useConversationClientTool } from "@elevenlabs/react";
import { useState } from "react";
function MapComponent() {
  const [location, setLocation] = useState({ lat: 0, lng: 0 });
  useConversationClientTool("getLocation", () => {
    return `${location.lat},${location.lng}`;
  });
  useConversationClientTool("setLocation", (params: { lat: number; lng: number }) => {
    setLocation(params);
    return "Location updated";
  });
  return <Map center={location} />;
}

Hooken använder alltid hanterarens senaste closure-värde, så du behöver inte oroa dig för inaktuell status.