JavaScript SDK

Installation

Installieren Sie das Paket über einen Paketmanager in Ihrem Projekt.

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

Verwendung

Diese Bibliothek ist primär für die Entwicklung in Vanilla-JavaScript-Projekten gedacht oder als Basis für Bibliotheken, die auf bestimmte Frameworks zugeschnitten sind. Prüfen Sie, ob Ihr Framework eine eigene Bibliothek hat. Sie können diese Bibliothek jedoch in jedem JavaScript-basierten Projekt verwenden.

Unterhaltung initialisieren

Erstellen Sie zunächst mit Conversation.startSession eine neue Unterhaltungssitzung:

const conversation = await Conversation.startSession(options);

Dadurch wird eine Verbindung hergestellt und das Mikrofon für die Kommunikation mit dem ElevenLabs Agents-Agenten verwendet. Erklären Sie den Mikrofonzugriff in der UI Ihrer App und erlauben Sie ihn, bevor Sie die Unterhaltung starten:

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

Sitzungs-Konfiguration

Die an startSession übergebenen Optionen legen fest, wie die Sitzung hergestellt wird. Unterhaltungen können mit öffentlichen oder privaten Agenten gestartet werden.

Öffentliche Agenten

Agenten, die keine Authentifizierung erfordern, können mithilfe der Agent-ID eine Unterhaltung starten. Die Agent-ID erhalten Sie über die ElevenLabs UI.

Bei öffentlichen Agenten können Sie die ID direkt verwenden:

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

Private Agenten

Wenn die Unterhaltung eine Autorisierung erfordert, müssen Sie Ihrem Server einen eigenen Endpunkt hinzufügen. Dieser fordert über die ElevenLabs API entweder eine signierte URL an (bei Verwendung des WebSockets-Verbindungstyps) oder ein Unterhaltungstoken (bei Verwendung von WebRTC) und gibt es an den Client zurück.

Hier ist ein Beispiel für eine WebSocket-Verbindung:

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

Hier ist ein Beispiel für 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);
});

Sobald Sie das Token haben, startet die Übergabe an startSession die Unterhaltung über WebRTC.

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

Optionale Callbacks

Mit den an startSession übergebenen Optionen können Sie auch optionale Callbacks registrieren:

• onConnect – Handler, der aufgerufen wird, wenn die WebSocket-Verbindung für die Unterhaltung hergestellt ist.
• onDisconnect – Handler, der aufgerufen wird, wenn die WebSocket-Verbindung für die Unterhaltung beendet wird.
• onMessage – Handler, der aufgerufen wird, wenn eine neue Textnachricht eingeht. Dabei kann es sich um vorläufige oder endgültige Transkriptionen der Nutzersprache oder von einem LLM erzeugte Antworten handeln. Primär für die Verarbeitung der Unterhaltungstranskription.
• onError – Handler, der aufgerufen wird, wenn ein Fehler auftritt.
• onStatusChange – Handler, der bei jeder Änderung des Verbindungsstatus aufgerufen wird. Möglich sind connected, connecting und disconnected (anfänglich).
• onModeChange – Handler, der aufgerufen wird, wenn sich ein Status ändert, z. B. wenn der Agent von speaking zu listening wechselt oder umgekehrt.
• onCanSendFeedbackChange – Handler, der aufgerufen wird, wenn das Senden von Feedback verfügbar oder nicht verfügbar wird.
• onAudioAlignment – Handler, der aufgerufen wird, wenn Audio-Alignment-Daten eingehen. Diese liefern Timing-Informationen auf Zeichenebene für die Sprache des Agenten.

Rückgabewert

startSession gibt eine Unterhaltungsinstanz zurück (VoiceConversation oder TextConversation, je nach Modus), mit der Sie die Sitzung steuern können. Die Methode löst einen Fehler aus, wenn die Sitzung nicht hergestellt werden kann. Das kann passieren, wenn der Nutzer den Mikrofonzugriff verweigert oder die Verbindung fehlschlägt.

endSession

Eine Methode zum manuellen Beenden der Unterhaltung. Sie beendet die Unterhaltung und trennt die WebSocket-Verbindung. Danach ist die Unterhaltungsinstanz nicht mehr verwendbar und kann sicher verworfen werden.

await conversation.endSession();

getId

Eine Methode, die die Unterhaltungs-ID zurückgibt.

const id = conversation.getId();

setVolume

Eine Methode zum Festlegen der Ausgabelautstärke der Unterhaltung. Akzeptiert ein Objekt mit einem Lautstärkefeld zwischen 0 und 1.

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

getInputVolume / getOutputVolume

Methoden, die die aktuelle Eingabe-/Ausgabelautstärke auf einer Skala von 0 bis 1 zurückgeben, wobei 0 -100 dB und 1 -30 dB entspricht.

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

sendFeedback

Eine Methode zum Senden von binärem Feedback an den Agenten. Die Methode akzeptiert einen booleschen Wert, wobei true positives und false negatives Feedback bedeutet.

Feedback bezieht sich immer auf die letzte Antwort des Agenten und kann nur einmal pro Antwort gesendet werden.

Über onCanSendFeedbackChange können Sie feststellen, ob Feedback zum jeweiligen Zeitpunkt gesendet werden kann.

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

sendContextualUpdate

Eine Methode zum Senden kontextbezogener Updates an den Agenten. Damit können Sie den Agenten über Nutzeraktionen informieren, die nicht direkt mit der Unterhaltung zusammenhängen, aber seine Antworten beeinflussen können.

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

sendUserMessage

Sendet eine Textnachricht an den Agenten.

Damit kann der Nutzer die Nachricht eingeben, statt das Mikrofon zu verwenden. Anders als bei sendContextualUpdate wird dies als Nutzernachricht behandelt und veranlasst den Agenten, in der Unterhaltung zu antworten.

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

sendUserActivity

Benachrichtigt den Agenten über Nutzeraktivität.

Der Agent versucht mindestens 2 Sekunden lang nicht zu sprechen, nachdem Nutzeraktivität erkannt wurde.

Damit können Sie verhindern, dass der Agent den Nutzer beim Tippen unterbricht.

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

setMicMuted

Eine Methode zum Stummschalten bzw. Aktivieren des Mikrofons.

// Mute the microphone
conversation.setMicMuted(true);
// Unmute the microphone
conversation.setMicMuted(false);

changeInputDevice

Ermöglicht das Ändern des Audioeingabegeräts während einer aktiven Sprachunterhaltung. Diese Methode ist nur für Sprachunterhaltungen verfügbar.

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

Wenn die Geräte-ID ungültig ist, wird stattdessen das Standardgerät verwendet.

changeOutputDevice

Ermöglicht das Ändern des Audioausgabegeräts während einer aktiven Sprachunterhaltung. Diese Methode ist nur für Sprachunterhaltungen verfügbar.

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

Methoden, die Uint8Arrays mit den aktuellen Eingabe-/Ausgabefrequenzdaten zurückgeben. Weitere Informationen finden Sie unter AnalyserNode.getByteFrequencyData.