> 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** > > Zie ook het [ElevenAgents-overzicht](/docs/nl/eleven-agents/overview) ## Installatie Installeer het pakket in je project via een package manager. ```shell npm install @elevenlabs/client # or yarn add @elevenlabs/client # or pnpm install @elevenlabs/client ``` > **Tip** > > Upgrade je vanaf een eerdere versie? Voer `npx skills add elevenlabs/packages` uit om de > vaardigheid `elevenlabs:sdk-migration` voor je AI-codingagent te installeren. Deze automatiseert importwijzigingen en API- > updates. ## 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`: ```js 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: ```js // 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](https://elevenlabs.io/app/conversational-ai). Voor openbare agents kun je de ID rechtstreeks gebruiken: ```js const conversation = await Conversation.startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6", }); ``` > **Note** > > Het verbindingstype wordt automatisch afgeleid op basis van de conversatiemodus. Spraakconversaties > gebruiken standaard WebRTC en alleen-tekstconversaties gebruiken WebSocket. Je kunt desgewenst nog steeds expliciet > `connectionType: 'webrtc'` of `connectionType: 'websocket'` opgeven. ##### Private agents Als de conversatie autorisatie vereist, moet je een speciaal endpoint aan je server toevoegen dat via de [ElevenLabs API](https://elevenlabs.io/docs/overview/intro) 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: ```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, }); ``` Hier is een voorbeeld voor 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); }); ``` Zodra je het token hebt, start je de conversatie via WebRTC door het aan `startSession` door te geven. ```js // 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. > **Warning** > > Niet alle clientevents zijn standaard ingeschakeld voor een agent. Als je een callback hebt ingeschakeld maar > geen events ontvangt, controleer dan of voor je ElevenLabs-agent het bijbehorende event > is ingeschakeld. Dit kun je doen op het tabblad "Advanced" in de agentinstellingen in het ElevenLabs-dashboard. #### 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. ```js await conversation.endSession(); ``` **getId** Een methode die de conversatie-ID retourneert. ```js 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. ```js 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. ```js 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. ```js 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. ```js 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. ```js 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. ```js textInput.addEventListener("input", () => { conversation.sendUserActivity(); }); ``` **setMicMuted** Een methode om de microfoon te dempen of het dempen op te heffen. ```js // 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. > **Note** > > In de WebRTC-modus zijn de invoerindeling en samplefrequentie vast ingesteld op respectievelijk `pcm` en `48000`. > Het wijzigen van deze waarden bij het wijzigen van het invoerapparaat heeft geen effect. ```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", }); ``` 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. > **Note** > > In de WebRTC-modus zijn de uitvoerindeling en samplefrequentie vast ingesteld op respectievelijk `pcm` en `48000`. > Het wijzigen van deze waarden bij het wijzigen van het uitvoerapparaat heeft geen effect. ```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** > > Wisselen van apparaat werkt alleen voor spraakconversaties. Als geen specifieke `deviceId` is opgegeven, > gebruikt de browser de standaardapparaatselectie. Je kunt beschikbare apparaten opsommen met de > [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices) > API. **getInputByteFrequencyData / getOutputByteFrequencyData** Methoden die `Uint8Array`s retourneren met de huidige invoer-/uitvoerfrequentiegegevens. Zie [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) voor meer informatie. > **Note** > > Deze methoden zijn alleen beschikbaar voor spraakconversaties. In de WebRTC-modus is de audio vast ingesteld op > `pcm_48000`, wat betekent dat visualisaties met de geretourneerde gegevens andere patronen kunnen tonen > dan WebSocket-verbindingen.