> 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**
>
> Se [översikten över ElevenAgents](/docs/sv/eleven-agents/overview) för en förklaring av hur
> ElevenAgents fungerar.

## Installation

Installera paketet i ditt projekt via en pakethanterare.

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

> **Tip**
>
> Uppgraderar du från en tidigare version? Kör `npx skills add elevenlabs/packages` för att installera
> färdigheten `elevenlabs:sdk-migration` för din AI-kodningsagent, som automatiserar ändringar av importer,
> omslutning med `ConversationProvider` och API-uppdateringar.

> **Note**
>
> `@elevenlabs/react` återexporterar allt från `@elevenlabs/client`, så du behöver inte installera
> båda paketen.

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

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

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.

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

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

##### 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).

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

> **Note**
>
> För bättre renderingsprestanda bör du överväga att använda [detaljerade hooks](#granular-hooks) i stället.
> `useConversation` utlöser en omrendering vid alla statusändringar, medan de detaljerade hooks endast
> omrenderar när deras specifika del av statusen ändras.

#### Initiera konversation

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

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

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

Alternativen omfattar:

* **clientTools** - objektdefinition för klientverktyg som kan anropas av agenten. [Se nedan](#client-tools) för mer information.
* **overrides** - objektdefinition för åsidosättningar av konversationsinställningar. [Se nedan](#conversation-overrides) för mer information.
* **textOnly** - om konversationen ska köras i läget endast text. [Se nedan](#text-only) 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](https://elevenlabs.io/app/agents), där du kan namnge och beskriva olika verktyg samt konfigurera parametrarna som skickas av agenten.

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

> **Note**
>
> För ett mer React-anpassat sätt att registrera klientverktyg, se
> [useConversationClientTool](#useconversationclienttool).

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

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

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

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

##### Kontrollerad status

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

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

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

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

> **Note**
>
> Anslutningstypen härleds automatiskt utifrån konversationsläget. Röstkonversationer
> använder WebRTC och konversationer med endast text använder WebSocket som standard. Du kan fortfarande uttryckligen ange
> `connectionType` vid behov.

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

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.

#### WebSocket-anslutning

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

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

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

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

##### setVolume

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

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

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

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

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

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

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

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

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

> **Note**
>
> Enhetsbyte fungerar endast för röstkonversationer. Om inget specifikt `deviceId` anges använder
> webbläsaren sitt standardval av enhet. Du kan lista tillgängliga enheter med
> API:t [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices).

##### getId

Returnerar det aktuella konversations-ID:t.

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

```js
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](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) för mer information.

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

> **Note**
>
> Dessa metoder är endast tillgängliga för röstkonversationer. I WebRTC-läge är ljudet hårdkodat för att
> använda `pcm_48000`, vilket innebär att visualiseringar som använder returnerade data kan visa andra mönster
> än WebSocket-anslutningar.

##### sendMCPToolApprovalResult

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

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

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

---

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

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

Returnerar aktuell anslutningsstatus och ett valfritt statusmeddelande.

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

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

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

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

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

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

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

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