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

# SDK React

> **Info**
>
> Zobacz [omówienie ElevenAgents](/docs/pl/eleven-agents/overview), aby dowiedzieć się, jak działa
> ElevenAgents.

## Instalacja

Zainstaluj pakiet w projekcie za pomocą menedżera pakietów.

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

> **Tip**
>
> Aktualizujesz starszą wersję? Uruchom `npx skills add elevenlabs/packages`, aby zainstalować
> umiejętność `elevenlabs:sdk-migration` dla swojego agenta AI do programowania. Automatyzuje ona zmiany importów,
> opakowanie w `ConversationProvider` i aktualizacje API.

> **Note**
>
> `@elevenlabs/react` ponownie eksportuje wszystko z `@elevenlabs/client`, więc nie musisz instalować
> obu pakietów.

## Użycie

Oto minimalny działający przykład, który łączy się z agentem i pozwala użytkownikowi rozpocząć oraz zakończyć rozmowę głosową:

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

Poniższe sekcje szczegółowo wyjaśniają każdą część.

### ConversationProvider

Wszystkie hooki rozmowy muszą być używane wewnątrz `ConversationProvider`. Owiń nim aplikację (lub odpowiednie poddrzewo).

```tsx
import { ConversationProvider } from "@elevenlabs/react";

function App() {
  return (
    <ConversationProvider>
      <YourComponents />
    </ConversationProvider>
  );
}
```

#### Właściwości providera

Provider przyjmuje te same opcje co `useConversation` — w tym callbacki, narzędzia klienta, nadpisania i lokalizację serwera — więc możesz je skonfigurować na poziomie providera zamiast w każdym hooku.

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

##### Kontrolowany stan wyciszenia

Provider obsługuje właściwości `isMuted` i `onMutedChange` do kontrolowanego zarządzania stanem wyciszenia. Dzięki temu możesz przechowywać stan wyciszenia poza nim, np. między sesjami.

```tsx
const [muted, setMuted] = useState(false);

<ConversationProvider isMuted={muted} onMutedChange={setMuted}>
  <YourComponents />
</ConversationProvider>;
```

### useConversation

Wygodny hook React, który łączy wszystkie szczegółowe hooki w jedną wartość zwracaną. Wymaga nadrzędnego `ConversationProvider`.

> **Note**
>
> Dla lepszej wydajności renderowania rozważ użycie [szczegółowych hooków](#granular-hooks).
> `useConversation` powoduje ponowne renderowanie przy każdej zmianie stanu, podczas gdy szczegółowe hooki
> renderują ponownie tylko wtedy, gdy zmienia się ich konkretny fragment stanu.

#### Inicjowanie rozmowy

```tsx
import { useConversation } from "@elevenlabs/react";

function MyComponent() {
  const conversation = useConversation();
  // ...
}
```

Pamiętaj, że ElevenAgents wymaga dostępu do mikrofonu w rozmowach głosowych. Zanim rozpocznie się rozmowa, rozważ wyjaśnienie tego w interfejsie aplikacji i umożliwienie dostępu.

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

#### Opcje

Hook można opcjonalnie zainicjować z opcjami. Możesz je też przekazać na poziomie `ConversationProvider`.

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

Dostępne opcje:

* **clientTools** - definicja obiektu narzędzi klienta, które może wywoływać agent. Szczegóły znajdziesz [poniżej](#client-tools).
* **overrides** - definicja obiektu nadpisań ustawień rozmowy. Szczegóły znajdziesz [poniżej](#conversation-overrides).
* **textOnly** - czy rozmowa ma działać w trybie tylko tekstowym. Szczegóły znajdziesz [poniżej](#text-only).
* **serverLocation** - określa lokalizację serwera (`"us"`, `"eu-residency"`, `"in-residency"`, `"global"`). Domyślnie: `"us"`.

#### Przegląd callbacków

* **onConnect** - procedura wywoływana po ustanowieniu połączenia rozmowy.
* **onDisconnect** - procedura wywoływana po zakończeniu połączenia rozmowy.
* **onMessage** - procedura wywoływana po otrzymaniu nowej wiadomości. Mogą to być wstępne lub końcowe transkrypcje głosu użytkownika, odpowiedzi wygenerowane przez LLM albo komunikaty debugowania, gdy włączona jest opcja debugowania.
* **onError** - procedura wywoływana po wystąpieniu błędu.
* **onAudio** - procedura wywoływana po otrzymaniu danych audio.
* **onModeChange** - procedura wywoływana po zmianie trybu rozmowy (mówienie/słuchanie).
* **onStatusChange** - procedura wywoływana po zmianie stanu połączenia.
* **onCanSendFeedbackChange** - procedura wywoływana po zmianie możliwości wysłania opinii.
* **onDebug** - procedura wywoływana, gdy dostępne są informacje debugowania.
* **onUnhandledClientToolCall** - procedura wywoływana po napotkaniu nieobsłużonego wywołania narzędzia klienta.
* **onVadScore** - procedura wywoływana po zmianie wyniku wykrywania aktywności głosowej.
* **onAudioAlignment** - procedura wywoływana po otrzymaniu danych synchronizacji audio, zapewniających informacje o czasie na poziomie znaków dla mowy agenta.
* **onAgentChatResponsePart** - procedura wywoływana z tekstem odpowiedzi agenta w trakcie jej generowania, jako zdarzenia rozpoczęcia, delty i zakończenia. Zawsze wysyłana w trybie tylko tekstowym; w rozmowach głosowych włącz `agent_chat_response_part` w konfiguracji `client_events` agenta.

##### Narzędzia klienta

Narzędzia klienta pozwalają agentowi wywoływać funkcje po stronie klienta. Możesz dzięki nim uruchamiać działania w kliencie, np. otworzyć modal lub wykonać wywołanie API w imieniu użytkownika.

Definicja narzędzi klienta to obiekt funkcji i musi być zgodna z konfiguracją w [interfejsie ElevenLabs](https://elevenlabs.io/app/agents), gdzie możesz nazwać i opisać różne narzędzia oraz skonfigurować parametry przekazywane przez agenta.

```ts
const conversation = useConversation({
  clientTools: {
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);

      return "Message displayed";
    },
  },
});
```

Jeśli funkcja zwraca wartość, jest ona przekazywana agentowi jako odpowiedź.

Aby agent czekał na odpowiedź i mógł na nią zareagować, narzędzie musi być w interfejsie ElevenLabs wyraźnie ustawione tak, by blokowało rozmowę. W przeciwnym razie agent zakłada powodzenie i kontynuuje rozmowę.

> **Note**
>
> Bardziej zgodne z podejściem React rozwiązanie do rejestrowania narzędzi klienta znajdziesz w
> [useConversationClientTool](#useconversationclienttool).

##### Nadpisania rozmowy

Możesz nadpisać różne ustawienia rozmowy i ustawiać je dynamicznie na podstawie innych interakcji użytkownika.

Obsługujemy nadpisywanie różnych ustawień. Są one opcjonalne i pozwalają dostosować rozmowę.

Dostępne są następujące ustawienia:

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

##### Tylko tekst

Jeśli twój agent jest skonfigurowany do działania w trybie tylko tekstowym, czyli nie wysyła ani nie odbiera wiadomości audio, możesz użyć tej flagi, by korzystać z lżejszej wersji rozmowy. W takim przypadku użytkownik nie zostanie poproszony o uprawnienia do mikrofonu i nie zostanie utworzony kontekst audio.

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

##### Kontrolowany stan

Możesz bezpośrednio kontrolować wybrane elementy stanu rozmowy przez opcje hooka:

```ts
const [micMuted, setMicMuted] = useState(false);

const conversation = useConversation({
  micMuted,
  // ... other options
});

// Update controlled state
setMicMuted(true); // This will automatically mute the microphone
```

##### Rezydencja danych

Możesz określić, z którym regionem serwerów ElevenLabs ma zostać nawiązane połączenie. Więcej informacji znajdziesz w [przewodniku po rezydencji danych](/docs/pl/overview/administration/data-residency).

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

#### Metody

##### startSession

Metoda `startSession` ustanawia połączenie i zaczyna używać mikrofonu do komunikacji z agentem ElevenLabs Agents. Metoda przyjmuje obiekt opcji, w którym wymagane jest `signedUrl`, `conversationToken` lub `agentId`.

Identyfikator agenta można uzyskać w [interfejsie ElevenLabs](https://elevenlabs.io/app/agents).

Zalecamy też przekazywanie własnych identyfikatorów użytkowników końcowych, aby mapować rozmowy na użytkowników.

> **Note**
>
> Typ połączenia jest automatycznie wybierany na podstawie trybu rozmowy. Rozmowy głosowe
> używają WebRTC, a rozmowy tylko tekstowe domyślnie używają WebSocket. W razie potrzeby nadal możesz wyraźnie określić
> `connectionType`.

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

W przypadku agentów publicznych (czyli agentów bez włączonego uwierzytelniania) wymagany jest tylko `agentId`.

Jeśli rozmowa wymaga autoryzacji, użyj REST API, aby wygenerować podpisane linki dla połączenia WebSocket lub token rozmowy dla połączenia WebRTC.

`startSession` zwraca obietnicę z `conversationId`. Ta wartość to globalnie unikalny identyfikator rozmowy, którego możesz użyć do rozróżniania rozmów.

#### Połączenie WebSocket

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

#### Połączenie WebRTC

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

Metoda ręcznego zakończenia rozmowy. Rozłącza i kończy rozmowę.

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

##### setVolume

Ustawia głośność wyjściową rozmowy. Przyjmuje obiekt z polem `volume` o wartości od 0 do 1.

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

##### sendUserMessage

Wysyła wiadomość tekstową do agenta.

Możesz użyć jej, by pozwolić użytkownikowi wpisać wiadomość zamiast korzystać z mikrofonu. W przeciwieństwie do `sendContextualUpdate`, zostanie to potraktowane jako wiadomość użytkownika i skłoni agenta do wykonania swojej tury w rozmowie.

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

Wysyła agentowi informacje kontekstowe, które nie wywołają odpowiedzi.

```js
const { sendContextualUpdate } = useConversation();

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

##### sendFeedback

Przekazuje opinię o jakości rozmowy. Pomaga to poprawiać działanie agenta.

```js
const { sendFeedback } = useConversation();

sendFeedback(true); // positive feedback
sendFeedback(false); // negative feedback
```

##### sendUserActivity

Powiadamia agenta o aktywności użytkownika, aby zapobiec przerwaniu. Przydatne, gdy użytkownik aktywnie korzysta z aplikacji, a agent powinien przestać mówić, np. gdy użytkownik pisze na czacie.

Agent przestanie mówić na około 2 sekundy po otrzymaniu tego sygnału.

```js
const { sendUserActivity } = useConversation();

// Call this when user is typing to prevent interruption
sendUserActivity();
```

##### changeInputDevice

Zmienia urządzenie wejściowe audio podczas aktywnej rozmowy głosowej. Ta metoda jest dostępna tylko w rozmowach głosowych.

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

##### changeOutputDevice

Zmienia urządzenie wyjściowe audio podczas aktywnej rozmowy głosowej. Ta metoda jest dostępna tylko w rozmowach głosowych.

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

> **Note**
>
> Przełączanie urządzeń działa tylko w rozmowach głosowych. Jeśli nie podasz konkretnego `deviceId`,
> przeglądarka użyje domyślnego urządzenia. Dostępne urządzenia możesz wyświetlić za pomocą
> API [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices).

##### getId

Zwraca identyfikator bieżącej rozmowy.

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

##### getInputVolume / getOutputVolume

Metody zwracające bieżące poziomy głośności wejściowej/wyjściowej (skala 0–1).

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

##### getInputByteFrequencyData / getOutputByteFrequencyData

Metody zwracające `Uint8Array` zawierające bieżące dane częstotliwości wejściowej/wyjściowej. Więcej informacji znajdziesz w [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData).

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

> **Note**
>
> Te metody są dostępne tylko w rozmowach głosowych. W trybie WebRTC audio jest na stałe ustawione na
> `pcm_48000`, więc wizualizacje korzystające ze zwracanych danych mogą pokazywać inne wzory
> niż połączenia WebSocket.

##### sendMCPToolApprovalResult

Wysyła wynik zatwierdzenia wywołań narzędzi MCP (Model Context Protocol).

```js
const { sendMCPToolApprovalResult } = useConversation();

// Approve a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", true);

// Reject a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", false);
```

#### Wartości zwracane

Oprócz powyższych metod `useConversation` zwraca następujący reaktywny stan:

* **status** - bieżący stan połączenia (`"disconnected"`, `"connecting"`, `"connected"`).
* **isSpeaking** - czy agent aktualnie mówi.
* **isListening** - czy agent aktualnie słucha.
* **mode** - bieżący tryb rozmowy (`"speaking"` lub `"listening"`).
* **isMuted** - czy mikrofon jest aktualnie wyciszony.
* **setMuted** - funkcja wyciszająca/włączająca mikrofon.
* **canSendFeedback** - czy można przesłać opinię o bieżącej rozmowie.
* **message** - ostatnia wiadomość z rozmowy.

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

---

## Szczegółowe hooki

Dla lepszej wydajności renderowania użyj tych hooków zamiast `useConversation`. Każdy hook subskrybuje tylko swój konkretny fragment stanu, więc komponenty renderują się ponownie tylko wtedy, gdy zmieniają się dane, z których korzystają.

Wszystkie szczegółowe hooki wymagają nadrzędnego `ConversationProvider`.

### useConversationControls

Zwraca metody działania do sterowania rozmową. Ten hook nie powoduje ponownego renderowania, ponieważ udostępnia tylko stabilne referencje funkcji.

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

Zwraca bieżący stan połączenia i opcjonalny komunikat stanu.

```tsx
import { useConversationStatus } from "@elevenlabs/react";

function StatusIndicator() {
  const { status, message } = useConversationStatus();

  return <p>Status: {status}</p>; // "disconnected" | "connecting" | "connected"
}
```

### useConversationInput

Zwraca stan wyciszenia oraz setter do przełączania mikrofonu.

```tsx
import { useConversationInput } from "@elevenlabs/react";

function MuteToggle() {
  const { isMuted, setMuted } = useConversationInput();

  return <button onClick={() => setMuted(!isMuted)}>{isMuted ? "Unmute" : "Mute"}</button>;
}
```

### useConversationMode

Zwraca stan mówienia/słuchania agenta.

```tsx
import { useConversationMode } from "@elevenlabs/react";

function ModeIndicator() {
  const { mode, isSpeaking, isListening } = useConversationMode();

  return <p>Agent is {isSpeaking ? "speaking" : "listening"}</p>;
}
```

### useConversationFeedback

Zwraca dostępność opinii i metodę jej przesłania.

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

Zwraca surową instancję rozmowy. To rozwiązanie awaryjne dla zaawansowanych przypadków użycia, gdy potrzebujesz bezpośredniego dostępu do bazowego obiektu `VoiceConversation` lub `TextConversation`.

```tsx
import { useRawConversation } from "@elevenlabs/react";

function Advanced() {
  const conversation = useRawConversation();
  // Access the raw conversation instance directly
}
```

---

## useConversationClientTool

Hook do dynamicznego rejestrowania narzędzi klienckich z komponentów React. Narzędzia są automatycznie wyrejestrowywane po odmontowaniu komponentu.

Przydaje się, gdy handler narzędzia potrzebuje dostępu do stanu komponentu lub propsów niedostępnych na poziomie providera.

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

Hook zawsze używa najnowszej wartości closure handlera, więc nie musisz martwić się o nieaktualny stan.