> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# React SDK

> **Info**
>
> Bekijk het [ElevenAgents-overzicht](/docs/nl/eleven-agents/overview) voor een uitleg over hoe
> ElevenAgents werkt.

## Installatie

Installeer het pakket in je project via een package manager.

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

> **Tip**
>
> Upgrade je vanaf een eerdere versie? Voer `npx skills add elevenlabs/packages` uit om de
> vaardigheid `elevenlabs:sdk-migration` voor je AI-codingagent te installeren. Deze automatiseert wijzigingen aan imports,
> het wrappen met `ConversationProvider` en API-updates.

> **Note**
>
> `@elevenlabs/react` exporteert alles uit `@elevenlabs/client` opnieuw, dus je hoeft
> niet beide pakketten te installeren.

## Gebruik

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

```tsx
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.

```tsx
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.

```tsx
<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).

```tsx
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`.

> **Note**
>
> Gebruik voor betere renderprestaties liever de [gedetailleerde hooks](#granular-hooks).
> `useConversation` veroorzaakt een re-render bij elke statuswijziging, terwijl de gedetailleerde hooks alleen
> re-renderen wanneer hun specifieke deel van de status verandert.

#### Gesprek initialiseren

```tsx
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.

```js
// 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`.

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

Opties zijn onder andere:

* **clientTools** - objectdefinitie voor client tools die door de agent kunnen worden aangeroepen. Bekijk [hieronder](#client-tools) de details.
* **overrides** - objectdefinitie voor overrides van gespreksinstellingen. Bekijk [hieronder](#conversation-overrides) de details.
* **textOnly** - of het gesprek alleen in tekstmodus moet worden uitgevoerd. Bekijk [hieronder](#text-only) 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](https://elevenlabs.io/app/agents), waar je verschillende tools kunt benoemen en beschrijven en de parameters kunt instellen die door de agent worden doorgegeven.

```ts
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.

> **Note**
>
> Voor een meer React-idiomatische aanpak voor het registreren van client tools, bekijk je
> [useConversationClientTool](#useconversationclienttool).

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

```ts
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.

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

##### Beheerde status

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

```ts
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](/docs/nl/overview/administration/data-residency).

```ts
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](https://elevenlabs.io/app/agents).

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

> **Note**
>
> Het verbindingstype wordt automatisch afgeleid op basis van de gespreksmodus. Spraakgesprekken
> gebruiken standaard WebRTC en alleen-tekstgesprekken gebruiken WebSocket. Je kunt indien nodig nog steeds expliciet
> `connectionType` opgeven.

```js
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.

#### WebSocket-verbinding

```js maxLines=0
// 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);
});
```

```js
// Client

const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();

await conversation.startSession({
  signedUrl,
});
```

#### WebRTC-verbinding

```js maxLines=0
// Node.js server

app.get("/conversation-token", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token 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 conversation token");
  }

  const body = await response.json();
  res.send(body.token);
});
```

```js
// Client

const response = await fetch("/conversation-token", yourAuthHeaders);
const conversationToken = await response.text();

await conversation.startSession({
  conversationToken,
});
```

##### endSession

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

```js
await conversation.endSession();
```

##### setVolume

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

```js
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.

```js
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.

```js
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.

```js
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.

```js
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.

```js
// 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.

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

> **Note**
>
> Wisselen tussen apparaten werkt alleen voor spraakgesprekken. Als er geen specifieke `deviceId` wordt opgegeven,
> gebruikt de browser de standaardapparaatselectie. Je kunt beschikbare apparaten weergeven met de
> [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices)
> API.

##### getId

Retourneert de huidige gespreks-ID.

```js
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).

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

##### getInputByteFrequencyData / getOutputByteFrequencyData

Methoden die `Uint8Array`s retourneren met de huidige invoer-/uitvoerfrequentiegegevens. Bekijk [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) voor meer informatie.

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

> **Note**
>
> Deze methoden zijn alleen beschikbaar voor spraakgesprekken. In de WebRTC-modus is de audio hardcoded om
> `pcm_48000` te gebruiken, wat betekent dat visualisaties met de geretourneerde gegevens mogelijk andere patronen tonen
> dan WebSocket-verbindingen.

##### sendMCPToolApprovalResult

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

```js
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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`.

```tsx
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.

```tsx
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.