React SDK

Installatie

Installeer het pakket in je project via een package manager.

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

Gebruik

Hier is een minimaal werkend voorbeeld dat verbinding maakt met een agent en de gebruiker een spraakgesprek laat starten en beëindigen:

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 de onderstaande secties wordt elk onderdeel uitgebreid uitgelegd.

ConversationProvider

Alle gesprekshooks moeten binnen een ConversationProvider worden gebruikt. Wrap je app (of de relevante substructuur) met deze provider.

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

Provider-props

De provider accepteert dezelfde opties als useConversation — waaronder callbacks, client tools, overrides en serverlocatie — zodat je ze op providerniveau kunt configureren in plaats van bij elke hookgebruiker.

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

Beheerde dempingsstatus

De provider ondersteunt de props isMuted en onMutedChange voor beheerd statusbeheer van demping. Zo kun je de dempingsstatus extern bewaren (bijvoorbeeld tussen sessies).

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

useConversation

Een handige React-hook die alle gedetailleerde hooks combineert in één returnwaarde. Vereist een bovenliggende ConversationProvider.

Gesprek initialiseren

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

Houd er rekening mee dat ElevenAgents microfoontoegang vereist voor spraakgesprekken. Overweeg om dit in de UI van je app uit te leggen en toegang toe te staan voordat het gesprek begint.

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

Opties

De hook kan optioneel met opties worden geïnitialiseerd. Je kunt deze ook doorgeven op het niveau van ConversationProvider.

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

Opties zijn onder andere:

• clientTools - objectdefinitie voor client tools die door de agent kunnen worden aangeroepen. Bekijk hieronder de details.
• overrides - objectdefinitie voor overrides van gespreksinstellingen. Bekijk hieronder de details.
• textOnly - of het gesprek alleen in tekstmodus moet worden uitgevoerd. Bekijk hieronder de details.
• serverLocation - geef de serverlocatie op ("us", "eu-residency", "in-residency", "global"). Standaard is dit "us".

Overzicht callbacks

• onConnect - handler die wordt aangeroepen wanneer de gespreksverbinding tot stand is gebracht.
• onDisconnect - handler die wordt aangeroepen wanneer de gespreksverbinding wordt beëindigd.
• onMessage - handler die wordt aangeroepen wanneer een nieuw bericht wordt ontvangen. Dit kunnen voorlopige of definitieve transcripties van de stem van de gebruiker zijn, antwoorden van een LLM of debugberichten wanneer een debugoptie is ingeschakeld.
• onError - handler die wordt aangeroepen wanneer er een fout optreedt.
• onAudio - handler die wordt aangeroepen wanneer audiogegevens worden ontvangen.
• onModeChange - handler die wordt aangeroepen wanneer de gespreksmodus verandert (spreken/luisteren).
• onStatusChange - handler die wordt aangeroepen wanneer de verbindingsstatus verandert.
• onCanSendFeedbackChange - handler die wordt aangeroepen wanneer de mogelijkheid om feedback te verzenden verandert.
• onDebug - handler die wordt aangeroepen wanneer debuginformatie beschikbaar is.
• onUnhandledClientToolCall - handler die wordt aangeroepen wanneer een niet-afgehandelde client-toolaanroep optreedt.
• onVadScore - handler die wordt aangeroepen wanneer de score voor spraakactiviteitsdetectie verandert.
• onAudioAlignment - handler die wordt aangeroepen wanneer audio-uitlijningsgegevens worden ontvangen, met timinginformatie per teken voor de spraak van de agent.
• onAgentChatResponsePart - handler die wordt aangeroepen met de antwoordtekst van de agent terwijl deze wordt gegenereerd, als start-, delta- en stopgebeurtenissen. Wordt altijd verzonden in alleen-tekstmodus; schakel voor spraakgesprekken agent_chat_response_part in de client_events-configuratie van de agent in.

Client tools

Met client tools kan een agent client-sidefunctionaliteit aanroepen. Je kunt hiermee acties in de client starten, zoals een modal openen of namens de gebruiker een API-aanroep uitvoeren.

De definitie van client tools is een object met functies en moet identiek zijn aan je configuratie in de ElevenLabs UI, waar je verschillende tools kunt benoemen en beschrijven en de parameters kunt instellen die door de agent worden doorgegeven.

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

Als de functie een waarde retourneert, wordt deze als antwoord teruggestuurd naar de agent.

De tool moet in de ElevenLabs UI expliciet zo worden ingesteld dat deze het gesprek blokkeert, zodat de agent op het antwoord kan wachten en erop kan reageren. Anders gaat de agent uit van succes en vervolgt het gesprek.

Gespreksoverrides

Je kunt verschillende instellingen van het gesprek overschrijven en deze dynamisch instellen op basis van andere gebruikersinteracties.

We ondersteunen het overschrijven van verschillende instellingen. Deze instellingen zijn optioneel en kunnen worden gebruikt om de gesprekservaring aan te passen.

De volgende instellingen zijn beschikbaar:

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

Alleen tekst

Als je agent is geconfigureerd om in alleen-tekstmodus te draaien, dat wil zeggen geen audioberichten verzendt of ontvangt, kun je deze flag gebruiken voor een lichtere versie van het gesprek. In dat geval wordt de gebruiker niet om microfoonmachtigingen gevraagd en wordt er geen audiocontext gemaakt.

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

Beheerde status

Je kunt bepaalde aspecten van de gespreksstatus rechtstreeks beheren via de hookopties:

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

Dataresidentie

Je kunt opgeven met welke ElevenLabs-serverregio verbinding moet worden gemaakt. Bekijk voor meer informatie de gids voor dataresidentie.

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

Methoden

startSession

De methode startSession brengt de verbinding tot stand en begint de microfoon te gebruiken om met de ElevenLabs Agents-agent te communiceren. De methode accepteert een optiesobject, waarbij signedUrl, conversationToken of agentId vereist is.

Je kunt de agent-ID verkrijgen via de ElevenLabs UI.

We raden ook aan je eigen eindgebruikers-ID’s door te geven om gesprekken aan je gebruikers te koppelen.

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

Voor public agents (dat wil zeggen agents waarvoor authenticatie niet is ingeschakeld) is alleen agentId vereist.

Als het gesprek autorisatie vereist, gebruik je de REST API om signed links voor een WebSocket-verbinding of een gesprekstoken voor een WebRTC-verbinding te genereren.

startSession retourneert een promise die wordt opgelost met een conversationId. De waarde is een wereldwijd unieke gespreks-ID die je kunt gebruiken om afzonderlijke gesprekken te identificeren.

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

Een methode om het gesprek handmatig te beëindigen. De methode verbreekt en beëindigt het gesprek.

await conversation.endSession();

setVolume

Stelt het uitvoervolume van het gesprek in. Accepteert een object met een veld volume tussen 0 en 1.

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

sendUserMessage

Verstuurt een tekstbericht naar de agent.

Kan worden gebruikt om de gebruiker het bericht te laten typen in plaats van de microfoon te gebruiken. In tegenstelling tot sendContextualUpdate wordt dit behandeld als een gebruikersbericht en zet het de agent aan om zijn beurt in het gesprek te nemen.

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

Stuurt contextuele informatie naar de agent die geen reactie activeert.

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

sendFeedback

Geef feedback over de gesprekskwaliteit. Dit helpt de prestaties van de agent te verbeteren.

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

sendUserActivity

Brengt de agent op de hoogte van gebruikersactiviteit om onderbrekingen te voorkomen. Handig wanneer de gebruiker de app actief gebruikt en de agent moet stoppen met spreken, bijvoorbeeld wanneer de gebruiker in een chat typt.

De agent stopt na ontvangst van dit signaal ongeveer 2 seconden met spreken.

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

changeInputDevice

Wissel het audio-invoerapparaat tijdens een actief spraakgesprek. Deze methode is alleen beschikbaar voor spraakgesprekken.

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

changeOutputDevice

Wissel het audio-uitvoerapparaat tijdens een actief spraakgesprek. Deze methode is alleen beschikbaar voor spraakgesprekken.

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

getId

Retourneert de huidige gespreks-ID.

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

getInputVolume / getOutputVolume

Methoden die de huidige invoer-/uitvoervolumeniveaus retourneren (schaal 0-1).

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

getInputByteFrequencyData / getOutputByteFrequencyData

Methoden die Uint8Arrays retourneren met de huidige invoer-/uitvoerfrequentiegegevens. Bekijk AnalyserNode.getByteFrequencyData voor meer informatie.

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

sendMCPToolApprovalResult

Verstuurt het goedkeuringsresultaat voor MCP-toolaanroepen (Model Context Protocol).

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

Returnwaarden

Naast de bovenstaande methoden retourneert useConversation de volgende reactieve status:

• status - de huidige verbindingsstatus ("disconnected", "connecting", "connected").
• isSpeaking - of de agent momenteel spreekt.
• isListening - of de agent momenteel luistert.
• mode - de huidige gespreksmodus ("speaking" of "listening").
• isMuted - of de microfoon momenteel is gedempt.
• setMuted - functie om de microfoon te dempen/demping op te heffen.
• canSendFeedback - of feedback voor het huidige gesprek kan worden verzonden.
• message - het meest recente bericht uit het gesprek.

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

Gedetailleerde hooks

Gebruik voor betere renderprestaties deze hooks in plaats van useConversation. Elke hook abonneert zich alleen op het specifieke deel van de status, zodat componenten alleen opnieuw renderen wanneer de gegevens die ze gebruiken veranderen.

Alle gedetailleerde hooks vereisen een bovenliggende ConversationProvider.

useConversationControls

Retourneert actiemethoden voor het beheren van het gesprek. Deze hook veroorzaakt geen re-renders, omdat deze alleen stabiele functiereferenties biedt.

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

Retourneert de huidige verbindingsstatus en een optioneel statusbericht.

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

useConversationInput

Retourneert de dempingsstatus en een setter om de microfoon in of uit te schakelen.

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

useConversationMode

Retourneert de spreek-/luisterstatus van de agent.

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

useConversationFeedback

Retourneert de beschikbaarheid van feedback en een methode om feedback te versturen.

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

Retourneert de onbewerkte gespreksinstantie. Dit is een uitweg voor geavanceerde gebruikssituaties waarin je directe toegang nodig hebt tot het onderliggende object VoiceConversation of TextConversation.

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

useConversationClientTool

Een hook om client tools dynamisch te registreren vanuit React-componenten. Tools worden automatisch afgemeld wanneer de component wordt ontkoppeld.

Dit is handig wanneer de handler van een tool toegang nodig heeft tot de status of props van de component die niet beschikbaar zijn op providerniveau.

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

De hook gebruikt altijd de nieuwste closurewaarde van de handler, dus je hoeft je geen zorgen te maken over verouderde status.