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

# JavaScript SDK

> **Info**
>
> Zobacz też [przegląd ElevenAgents](/docs/pl/eleven-agents/overview)

## Instalacja

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

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

> **Tip**
>
> Przechodzisz z wcześniejszej wersji? Uruchom `npx skills add elevenlabs/packages`, aby zainstalować
> umiejętność `elevenlabs:sdk-migration` dla agenta AI do kodowania, która automatyzuje zmiany importów i
> aktualizacje API.

## Użycie

Ta biblioteka jest przeznaczona głównie do tworzenia projektów w czystym JavaScript lub jako baza dla bibliotek dostosowanych do konkretnych frameworków.
Sprawdź, czy twój framework nie ma własnej biblioteki.
Możesz jednak używać tej biblioteki w każdym projekcie opartym na JavaScript.

### Inicjowanie rozmowy

Najpierw utwórz nową sesję rozmowy za pomocą `Conversation.startSession`:

```js
const conversation = await Conversation.startSession(options);
```

Spowoduje to nawiązanie połączenia i rozpoczęcie używania mikrofonu do komunikacji z agentem ElevenLabs Agents. Zanim rozpoczniesz rozmowę, wyjaśnij w interfejsie aplikacji, dlaczego potrzebujesz dostępu do mikrofonu, i poproś o zgodę:

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

#### Konfiguracja sesji

Opcje przekazane do `startSession` określają sposób nawiązania sesji. Rozmowy można rozpoczynać z agentami publicznymi lub prywatnymi.

##### Agenci publiczni

Agenci, którzy nie wymagają uwierzytelniania, mogą rozpocząć rozmowę za pomocą identyfikatora agenta. Identyfikator agenta znajdziesz w [interfejsie ElevenLabs](https://elevenlabs.io/app/conversational-ai).

W przypadku agentów publicznych możesz użyć identyfikatora bezpośrednio:

```js
const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});
```

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

##### Agenci prywatni

Jeśli rozmowa wymaga autoryzacji, musisz dodać na serwerze specjalny endpoint, który zażąda podpisanego URL-a (w przypadku połączenia WebSocket) lub tokenu rozmowy (w przypadku WebRTC) przez [API ElevenLabs](https://elevenlabs.io/docs/overview/intro), a następnie przekaże go klientowi.

Przykład połączenia 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}`,
    {
      method: "GET",
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.XI_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();

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

Przykład dla 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);
});
```

Gdy masz już token, przekazanie go do `startSession` rozpocznie rozmowę przez WebRTC.

```js
// Client

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

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

#### Opcjonalne callbacki

Opcje przekazane do `startSession` można też wykorzystać do zarejestrowania opcjonalnych callbacków:

* **onConnect** — funkcja wywoływana po nawiązaniu połączenia WebSocket rozmowy.
* **onDisconnect** — funkcja wywoływana po zakończeniu połączenia WebSocket rozmowy.
* **onMessage** — funkcja wywoływana po otrzymaniu nowej wiadomości tekstowej. Mogą to być wstępne lub końcowe transkrypcje głosu użytkownika albo odpowiedzi wygenerowane przez LLM. Służy głównie do obsługi transkrypcji rozmowy.
* **onError** — funkcja wywoływana po wystąpieniu błędu.
* **onStatusChange** — funkcja wywoływana przy każdej zmianie stanu połączenia. Może to być `connected`, `connecting` lub `disconnected` (początkowy).
* **onModeChange** — funkcja wywoływana przy zmianie stanu, np. gdy agent przełącza się z `speaking` na `listening` albo odwrotnie.
* **onCanSendFeedbackChange** — funkcja wywoływana, gdy możliwość wysłania opinii staje się dostępna lub niedostępna.
* **onAudioAlignment** — funkcja wywoływana po otrzymaniu danych wyrównania audio, które zawierają informacje o czasie na poziomie znaków dla wypowiedzi agenta.

> **Warning**
>
> Nie wszystkie zdarzenia klienta są domyślnie włączone dla agenta. Jeśli włączyłeś callback, ale
> nie otrzymujesz zdarzeń, upewnij się, że odpowiednie zdarzenie jest włączone dla twojego agenta
> ElevenLabs. Możesz to zrobić na karcie „Advanced” w ustawieniach agenta w panelu ElevenLabs.

#### Wartość zwracana

`startSession` zwraca instancję rozmowy (`VoiceConversation` lub `TextConversation`, zależnie od trybu), której możesz użyć do sterowania sesją. Metoda zgłosi błąd, jeśli nie uda się nawiązać sesji. Może się tak stać, gdy użytkownik odmówi dostępu do mikrofonu lub połączenie się nie powiedzie.

**endSession**

Metoda ręcznego zakończenia rozmowy. Kończy rozmowę i rozłącza WebSocket.
Następnie instancja rozmowy będzie bezużyteczna i można ją bezpiecznie odrzucić.

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

**getId**

Metoda zwracająca identyfikator rozmowy.

```js
const id = conversation.getId();
```

**setVolume**

Metoda ustawiająca głośność wyjściową rozmowy. Przyjmuje obiekt z polem głośności od 0 do 1.

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

**getInputVolume / getOutputVolume**

Metody zwracające bieżącą głośność wejścia/wyjścia w skali od `0` do `1`, gdzie `0` to -100 dB, a `1` to -30 dB.

```js
const inputVolume = await conversation.getInputVolume();
const outputVolume = await conversation.getOutputVolume();
```

**sendFeedback**

Metoda do wysyłania binarnej opinii do agenta. Przyjmuje wartość logiczną, gdzie `true` oznacza pozytywną opinię, a `false` — negatywną.

Opinia jest zawsze powiązana z najnowszą odpowiedzią agenta i można ją wysłać tylko raz na odpowiedź.

Możesz nasłuchiwać `onCanSendFeedbackChange`, aby sprawdzić, czy w danym momencie można wysłać opinię.

```js
conversation.sendFeedback(true); // positive feedback
conversation.sendFeedback(false); // negative feedback
```

**sendContextualUpdate**

Metoda do wysyłania aktualizacji kontekstowych do agenta. Możesz jej użyć, by poinformować agenta o działaniach użytkownika, które nie są bezpośrednio związane z rozmową, ale mogą wpłynąć na odpowiedzi agenta.

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

**sendUserMessage**

Wysyła wiadomość tekstową do agenta.

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

```js
sendButton.addEventListener("click", (e) => {
  conversation.sendUserMessage(textInput.value);
  textInput.value = "";
});
```

**sendUserActivity**

Powiadamia agenta o aktywności użytkownika.

Agent nie spróbuje mówić przez co najmniej 2 sekundy po wykryciu aktywności użytkownika.

Możesz tego użyć, aby agent nie przerywał użytkownikowi podczas pisania.

```js
textInput.addEventListener("input", () => {
  conversation.sendUserActivity();
});
```

**setMicMuted**

Metoda wyciszająca lub włączająca mikrofon.

```js
// Mute the microphone
conversation.setMicMuted(true);

// Unmute the microphone
conversation.setMicMuted(false);
```

**changeInputDevice**

Pozwala zmienić urządzenie wejściowe audio podczas aktywnej rozmowy głosowej. Ta metoda jest dostępna tylko dla rozmów głosowych.

> **Note**
>
> W trybie WebRTC format wejściowy i częstotliwość próbkowania są na stałe ustawione odpowiednio na `pcm` i `48000`.
> Zmiana tych wartości przy zmianie urządzenia wejściowego nie ma efektu.

```js
const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  // Alternatively you can provide a device ID when starting the session
  // Useful if you want to start the conversation with a non-default device
  inputDeviceId: "a1b2c3d4e5f6",
});

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

Jeśli identyfikator urządzenia jest nieprawidłowy, zostanie użyte urządzenie domyślne.

**changeOutputDevice**

Pozwala zmienić urządzenie wyjściowe audio podczas aktywnej rozmowy głosowej. Ta metoda jest dostępna tylko dla rozmów głosowych.

> **Note**
>
> W trybie WebRTC format wyjściowy i częstotliwość próbkowania są na stałe ustawione odpowiednio na `pcm` i `48000`.
> Zmiana tych wartości przy zmianie urządzenia wyjściowego nie ma efektu.

```js
const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  // Alternatively you can provide a device ID when starting the session
  // Useful if you want to start the conversation with a non-default device
  outputDeviceId: "a1b2c3d4e5f6",
});

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

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

**getInputByteFrequencyData / getOutputByteFrequencyData**

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

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