JavaScript SDK

Installatie

Installeer het pakket in je project via een package manager.

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

Gebruik

Deze bibliotheek is vooral bedoeld voor ontwikkeling in standaard JavaScript-projecten, of als basis voor bibliotheken die zijn afgestemd op specifieke frameworks. We raden aan te controleren of je specifieke framework een eigen bibliotheek heeft. Je kunt deze bibliotheek echter in elk JavaScript-gebaseerd project gebruiken.

Conversatie initialiseren

Maak eerst een nieuwe conversatiesessie met Conversation.startSession:

const conversation = await Conversation.startSession(options);

Hiermee wordt een verbinding tot stand gebracht en wordt de microfoon gebruikt om met de ElevenLabs Agents-agent te communiceren. Overweeg om in de UI van je app uit te leggen waarom microfoontoegang nodig is en om die toegang te vragen voordat je de conversatie start:

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

Sessiesconfiguratie

De opties die je aan startSession doorgeeft, bepalen hoe de sessie tot stand wordt gebracht. Je kunt conversaties starten met openbare of private agents.

Openbare agents

Je kunt agents die geen authenticatie vereisen gebruiken om een conversatie te starten met de agent-ID. Je kunt de agent-ID ophalen via de ElevenLabs-UI.

Voor openbare agents kun je de ID rechtstreeks gebruiken:

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

Private agents

Als de conversatie autorisatie vereist, moet je een speciaal endpoint aan je server toevoegen dat via de ElevenLabs API een ondertekende URL aanvraagt (bij gebruik van het WebSockets-verbindingstype) of een conversatietoken (bij gebruik van WebRTC), en dit terugstuurt naar de client.

Hier is een voorbeeld voor een WebSocket-verbinding:

// 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 is een voorbeeld voor 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);
});

Zodra je het token hebt, start je de conversatie via WebRTC door het aan startSession door te geven.

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

Optionele callbacks

Je kunt de opties die je aan startSession doorgeeft ook gebruiken om optionele callbacks te registreren:

• onConnect - handler die wordt aangeroepen wanneer de WebSocket-verbinding voor de conversatie tot stand is gebracht.
• onDisconnect - handler die wordt aangeroepen wanneer de WebSocket-verbinding voor de conversatie wordt beëindigd.
• onMessage - handler die wordt aangeroepen wanneer een nieuw tekstbericht wordt ontvangen. Dit kunnen voorlopige of definitieve transcripties van de stem van de gebruiker zijn, of antwoorden die door een LLM zijn geproduceerd. Wordt voornamelijk gebruikt voor het verwerken van conversatietranscripties.
• onError - handler die wordt aangeroepen wanneer er een fout optreedt.
• onStatusChange - handler die wordt aangeroepen wanneer de verbindingsstatus verandert. Kan connected, connecting en disconnected (initieel) zijn.
• onModeChange - handler die wordt aangeroepen wanneer een status verandert, bijvoorbeeld wanneer de agent overschakelt van speaking naar listening, of andersom.
• onCanSendFeedbackChange - handler die wordt aangeroepen wanneer feedback versturen beschikbaar of niet beschikbaar wordt.
• onAudioAlignment - handler die wordt aangeroepen wanneer audio-uitlijningsgegevens worden ontvangen en timinginformatie op tekenniveau voor spraak van de agent biedt.

Retourwaarde

startSession retourneert een conversatie-instantie (VoiceConversation of TextConversation, afhankelijk van de modus) waarmee je de sessie kunt beheren. De methode genereert een fout als de sessie niet tot stand kan worden gebracht. Dit kan gebeuren als de gebruiker microfoontoegang weigert of als de verbinding mislukt.

endSession

Een methode om de conversatie handmatig te beëindigen. De methode beëindigt de conversatie en verbreekt de WebSocket-verbinding. Daarna is de conversatie-instantie onbruikbaar en kun je deze veilig verwijderen.

await conversation.endSession();

getId

Een methode die de conversatie-ID retourneert.

const id = conversation.getId();

setVolume

Een methode om het uitvoervolume van de conversatie in te stellen. Accepteert een object met een volumeveld tussen 0 en 1.

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

getInputVolume / getOutputVolume

Methoden die het huidige invoer-/uitvoervolume retourneren op een schaal van 0 tot 1, waarbij 0 -100 dB is en 1 -30 dB.

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

sendFeedback

Een methode om binaire feedback naar de agent te sturen. De methode accepteert een booleaanse waarde, waarbij true positieve feedback vertegenwoordigt en false negatieve feedback.

Feedback wordt altijd gekoppeld aan het meest recente antwoord van de agent en kan slechts één keer per antwoord worden verstuurd.

Je kunt luisteren naar onCanSendFeedbackChange om te weten of je op dat moment feedback kunt versturen.

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

sendContextualUpdate

Een methode om contextuele updates naar de agent te sturen. Je kunt dit gebruiken om de agent te informeren over gebruikersacties die niet rechtstreeks met de conversatie verband houden, maar de antwoorden van de agent kunnen beïnvloeden.

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

sendUserMessage

Stuurt een tekstbericht naar de agent.

Je kunt dit gebruiken zodat de gebruiker het bericht typt in plaats van de microfoon te gebruiken. Anders dan sendContextualUpdate wordt dit behandeld als een gebruikersbericht en is het de beurt aan de agent in de conversatie.

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

sendUserActivity

Meldt gebruikersactiviteit aan de agent.

De agent probeert minimaal 2 seconden niet te spreken nadat gebruikersactiviteit is gedetecteerd.

Je kunt dit gebruiken om te voorkomen dat de agent de gebruiker onderbreekt tijdens het typen.

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

setMicMuted

Een methode om de microfoon te dempen of het dempen op te heffen.

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

changeInputDevice

Hiermee kun je tijdens een actieve spraakconversatie het audio-invoerapparaat wijzigen. Deze methode is alleen beschikbaar voor spraakconversaties.

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

Als de apparaat-ID ongeldig is, wordt in plaats daarvan het standaardapparaat gebruikt.

changeOutputDevice

Hiermee kun je tijdens een actieve spraakconversatie het audio-uitvoerapparaat wijzigen. Deze methode is alleen beschikbaar voor spraakconversaties.

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 retourneren met de huidige invoer-/uitvoerfrequentiegegevens. Zie AnalyserNode.getByteFrequencyData voor meer informatie.