React SDK

Installation

Installieren Sie das Paket über einen Paketmanager in Ihrem Projekt.

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

Verwendung

Hier ist ein minimales funktionierendes Beispiel, das eine Verbindung zu einem Agenten herstellt und Nutzern ermöglicht, eine Sprachunterhaltung zu starten und zu beenden:

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>
  );
}

In den folgenden Abschnitten wird jeder Teil im Detail erklärt.

ConversationProvider

Alle Conversation-Hooks müssen innerhalb eines ConversationProvider verwendet werden. Umschließen Sie Ihre App (oder den relevanten Teilbaum) mit diesem Provider.

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

Provider-Props

Der Provider akzeptiert dieselben Optionen wie useConversation – einschließlich Callbacks, Client-Tools, Überschreibungen und Serverstandort. So können Sie sie auf Provider-Ebene statt in jedem Hook-Consumer konfigurieren.

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

Gesteuerter Stummschaltungsstatus

Der Provider unterstützt die Props isMuted und onMutedChange für die gesteuerte Verwaltung des Stummschaltungsstatus. So können Sie den Status extern speichern, beispielsweise über mehrere Sitzungen hinweg.

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

useConversation

Ein praktischer React-Hook, der alle granularen Hooks in einem einzelnen Rückgabewert zusammenfasst. Erfordert einen übergeordneten ConversationProvider.

Unterhaltung initialisieren

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

Beachten Sie, dass ElevenAgents für Sprachunterhaltungen Zugriff auf das Mikrofon benötigt. Erklären Sie dies in der Benutzeroberfläche Ihrer App und ermöglichen Sie den Zugriff, bevor die Unterhaltung beginnt.

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

Optionen

Der Hook kann optional mit Optionen initialisiert werden. Diese können auch auf Ebene von ConversationProvider übergeben werden.

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

Zu den Optionen gehören:

• clientTools – Objektdefinition für Client-Tools, die vom Agenten aufgerufen werden können. Details finden Sie unten.
• overrides – Objektdefinition für Überschreibungen der Unterhaltungseinstellungen. Details finden Sie unten.
• textOnly – gibt an, ob die Unterhaltung im reinen Textmodus ausgeführt werden soll. Details finden Sie unten.
• serverLocation – gibt den Serverstandort an ("us", "eu-residency", "in-residency", "global"). Standard ist "us".

Überblick über Callbacks

• onConnect – Handler, der aufgerufen wird, wenn die Verbindungs zur Unterhaltung hergestellt ist.
• onDisconnect – Handler, der aufgerufen wird, wenn die Verbindung zur Unterhaltung beendet wird.
• onMessage – Handler, der aufgerufen wird, wenn eine neue Nachricht eingeht. Dabei kann es sich um vorläufige oder finale Transkriptionen der Nutzersprache, von einem LLM erzeugte Antworten oder Debug-Nachrichten handeln, wenn eine Debug-Option aktiviert ist.
• onError – Handler, der aufgerufen wird, wenn ein Fehler auftritt.
• onAudio – Handler, der aufgerufen wird, wenn Audiodaten eingehen.
• onModeChange – Handler, der aufgerufen wird, wenn sich der Unterhaltungsmodus ändert (Sprechen/Zuhören).
• onStatusChange – Handler, der aufgerufen wird, wenn sich der Verbindungsstatus ändert.
• onCanSendFeedbackChange – Handler, der aufgerufen wird, wenn sich die Möglichkeit zum Senden von Feedback ändert.
• onDebug – Handler, der aufgerufen wird, wenn Debuginformationen verfügbar sind.
• onUnhandledClientToolCall – Handler, der aufgerufen wird, wenn ein nicht behandelter Aufruf eines Client-Tools auftritt.
• onVadScore – Handler, der aufgerufen wird, wenn sich der Wert der Spracherkennung ändert.
• onAudioAlignment – Handler, der aufgerufen wird, wenn Audio-Alignment-Daten eingehen und Timing-Informationen auf Zeichenebene für die Sprache des Agenten bereitstellen.
• onAgentChatResponsePart – Handler, der den Antworttext des Agenten während seiner Generierung als Start-, Delta- und Stopp-Ereignisse erhält. Wird im reinen Textmodus immer gesendet. Aktivieren Sie für Sprachunterhaltungen agent_chat_response_part in der client_events-Konfiguration des Agenten.

Client-Tools

Mit Client-Tools kann der Agent clientseitige Funktionen aufrufen. Damit können Sie Aktionen im Client auslösen, etwa ein Modal öffnen oder im Namen des Nutzers einen API-Aufruf durchführen.

Die Definition der Client-Tools ist ein Objekt mit Funktionen und muss Ihrer Konfiguration in der ElevenLabs-Benutzeroberfläche entsprechen. Dort können Sie verschiedene Tools benennen und beschreiben sowie die vom Agenten übergebenen Parameter einrichten.

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

Wenn die Funktion einen Wert zurückgibt, wird er als Antwort an den Agenten übergeben.

Das Tool muss in der ElevenLabs-Benutzeroberfläche explizit so eingestellt werden, dass es die Unterhaltung blockiert, damit der Agent auf die Antwort warten und darauf reagieren kann. Andernfalls geht der Agent von Erfolg aus und setzt die Unterhaltung fort.

Überschreibungen der Unterhaltung

Sie können verschiedene Einstellungen der Unterhaltung überschreiben und sie anhand anderer Nutzerinteraktionen dynamisch festlegen.

Wir unterstützen das Überschreiben verschiedener Einstellungen. Diese Einstellungen sind optional und können verwendet werden, um das Unterhaltungserlebnis anzupassen.

Die folgenden Einstellungen sind verfügbar:

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,
    },
  },
});

Nur Text

Wenn Ihr Agent für den reinen Textmodus konfiguriert ist, also keine Audionachrichten sendet oder empfängt, können Sie dieses Flag verwenden, um eine schlankere Version der Unterhaltung zu nutzen. In diesem Fall werden Nutzer nicht nach Mikrofonberechtigungen gefragt und es wird kein Audiokontext erstellt.

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

Gesteuerter Status

Sie können bestimmte Aspekte des Unterhaltungsstatus direkt über die Hook-Optionen steuern:

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

Datenresidenz

Sie können festlegen, mit welcher ElevenLabs-Serverregion eine Verbindung hergestellt werden soll. Weitere Informationen finden Sie im Leitfaden zur Datenresidenz.

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

Methoden

startSession

Die Methode startSession stellt die Verbindung her und beginnt, über das Mikrofon mit dem ElevenLabs-Agents-Agenten zu kommunizieren. Die Methode akzeptiert ein Optionsobjekt, in dem signedUrl, conversationToken oder agentId erforderlich ist.

Die Agent-ID erhalten Sie über die ElevenLabs-Benutzeroberfläche.

Wir empfehlen außerdem, Ihre eigenen Endnutzer-IDs zu übergeben, um Unterhaltungen Ihren Nutzern zuzuordnen.

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 öffentliche Agenten, also Agenten ohne aktivierte Authentifizierung, ist nur agentId erforderlich.

Wenn die Unterhaltung eine Autorisierung erfordert, verwenden Sie die REST API, um signierte Links für eine WebSocket-Verbindung oder ein Unterhaltungstoken für eine WebRTC-Verbindung zu generieren.

startSession gibt ein Promise zurück, das zu einer conversationId aufgelöst wird. Der Wert ist eine global eindeutige Unterhaltungs-ID, mit der Sie separate Unterhaltungen identifizieren können.

// 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

Eine Methode zum manuellen Beenden der Unterhaltung. Die Methode trennt die Verbindung und beendet die Unterhaltung.

await conversation.endSession();

setVolume

Legt die Ausgabelautstärke der Unterhaltung fest. Akzeptiert ein Objekt mit einem Feld volume zwischen 0 und 1.

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

sendUserMessage

Sendet eine Textnachricht an den Agenten.

Kann verwendet werden, damit Nutzer die Nachricht eingeben können, statt das Mikrofon zu verwenden. Anders als sendContextualUpdate wird dies als Nutzernachricht behandelt und fordert den Agenten auf, seinen Zug in der Unterhaltung zu machen.

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

Sendet Kontextinformationen an den Agenten, die keine Antwort auslösen.

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

sendFeedback

Geben Sie Feedback zur Qualität der Unterhaltung. Dies hilft, die Leistung des Agenten zu verbessern.

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

sendUserActivity

Benachrichtigt den Agenten über Nutzeraktivität, um Unterbrechungen zu verhindern. Nützlich, wenn Nutzer die App aktiv verwenden und der Agent das Sprechen pausieren soll, etwa wenn Nutzer in einem Chat tippen.

Der Agent pausiert nach Erhalt dieses Signals für etwa 2 Sekunden.

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

changeInputDevice

Wechselt während einer aktiven Sprachunterhaltung das Audioeingabegerät. Diese Methode ist nur für Sprachunterhaltungen verfügbar.

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

changeOutputDevice

Wechselt während einer aktiven Sprachunterhaltung das Audioausgabegerät. Diese Methode ist nur für Sprachunterhaltungen verfügbar.

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

getId

Gibt die ID der aktuellen Unterhaltung zurück.

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

getInputVolume / getOutputVolume

Methoden, die die aktuellen Ein- und Ausgabelautstärken zurückgeben (Skala von 0 bis 1).

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

getInputByteFrequencyData / getOutputByteFrequencyData

Methoden, die Uint8Arrays mit den aktuellen Eingabe-/Ausgabefrequenzdaten zurückgeben. Weitere Informationen finden Sie unter AnalyserNode.getByteFrequencyData.

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

sendMCPToolApprovalResult

Sendet das Genehmigungsergebnis für MCP-Tool-Aufrufe (Model Context Protocol).

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

Rückgabewerte

Zusätzlich zu den oben genannten Methoden gibt useConversation folgenden reaktiven Status zurück:

• status – der aktuelle Verbindungsstatus ("disconnected", "connecting", "connected").
• isSpeaking – gibt an, ob der Agent gerade spricht.
• isListening – gibt an, ob der Agent gerade zuhört.
• mode – der aktuelle Unterhaltungsmodus ("speaking" oder "listening").
• isMuted – gibt an, ob das Mikrofon gerade stummgeschaltet ist.
• setMuted – Funktion zum Stummschalten bzw. Aktivieren des Mikrofons.
• canSendFeedback – gibt an, ob Feedback für die aktuelle Unterhaltung gesendet werden kann.
• message – die neueste Nachricht aus der Unterhaltung.

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

Granulare Hooks

Für eine bessere Render-Performance verwenden Sie diese Hooks statt useConversation. Jeder Hook abonniert nur seinen jeweiligen Statusbereich, sodass Komponenten nur erneut rendern, wenn sich die von ihnen verwendeten Daten ändern.

Alle granularen Hooks erfordern einen übergeordneten ConversationProvider.

useConversationControls

Gibt Aktionsmethoden zum Steuern der Unterhaltung zurück. Dieser Hook führt nicht zu erneutem Rendern, da er nur stabile Funktionsreferenzen bereitstellt.

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

Gibt den aktuellen Verbindungsstatus und eine optionale Statusmeldung zurück.

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

useConversationInput

Gibt den Stummschaltungsstatus und eine Setter-Funktion zum Umschalten des Mikrofons zurück.

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

useConversationMode

Gibt den Sprech-/Zuhörstatus des Agenten zurück.

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

useConversationFeedback

Gibt die Verfügbarkeit von Feedback und eine Methode zum Senden von Feedback zurück.

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

Gibt die unverarbeitete Unterhaltungsinstanz zurück. Dies ist ein Ausweg für erweiterte Anwendungsfälle, in denen Sie direkten Zugriff auf das zugrunde liegende Objekt VoiceConversation oder TextConversation benötigen.

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

useConversationClientTool

Ein Hook zum dynamischen Registrieren von Client-Tools aus React-Komponenten. Tools werden automatisch deregistriert, wenn die Komponente ausgehängt wird.

Das ist nützlich, wenn der Handler eines Tools Zugriff auf Komponentenstatus oder Props benötigt, die auf Provider-Ebene nicht verfügbar sind.

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} />;
}

Der Hook verwendet immer den aktuellen Closure-Wert des Handlers. Sie müssen sich daher keine Gedanken über veralteten Status machen.