JavaScript SDK

Instalacja

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

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

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:

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

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

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

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

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, a następnie przekaże go klientowi.

Przykład połączenia WebSocket:

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

// Client
const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();
const conversation = await Conversation.startSession({
  signedUrl,
});

Przykład dla WebRTC:

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

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

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

await conversation.endSession();

getId

Metoda zwracająca identyfikator rozmowy.

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.

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.

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

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.

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.

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.

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

setMicMuted

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

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

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.

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

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.