SDK React

Instalacja

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

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

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

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

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.

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

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.

Inicjowanie rozmowy

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.

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

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.
• overrides - definicja obiektu nadpisań ustawień rozmowy. Szczegóły znajdziesz poniżej.
• textOnly - czy rozmowa ma działać w trybie tylko tekstowym. Szczegóły znajdziesz poniżej.
• 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, gdzie możesz nazwać i opisać różne narzędzia oraz skonfigurować parametry przekazywane przez agenta.

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

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:

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.

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

Kontrolowany stan

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

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.

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.

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

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.

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

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

await conversation.endSession();

setVolume

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

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.

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.

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.

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.

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.

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

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

getId

Zwraca identyfikator bieżącej rozmowy.

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

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.

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

sendMCPToolApprovalResult

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

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.

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.

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.

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.

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.

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.

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.

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.

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.