> 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. # SDK JavaScript > **Info** > > Consultez également la [présentation d’ElevenAgents](/docs/fr/eleven-agents/overview) ## Installation Installez le package dans votre projet via votre gestionnaire de packages. ```shell npm install @elevenlabs/client # or yarn add @elevenlabs/client # or pnpm install @elevenlabs/client ``` > **Tip** > > Vous effectuez une mise à niveau depuis une version antérieure ? Exécutez `npx skills add elevenlabs/packages` pour installer la compétence > `elevenlabs:sdk-migration` pour votre agent de codage IA, qui automatise les modifications d’importation et les > mises à jour de l’API. ## Utilisation Cette bibliothèque est principalement conçue pour le développement de projets JavaScript natifs, ou comme base pour des bibliothèques adaptées à des frameworks spécifiques. Nous vous recommandons de vérifier si votre framework dispose de sa propre bibliothèque. Toutefois, vous pouvez utiliser cette bibliothèque dans tout projet basé sur JavaScript. ### Initialiser une conversation Commencez par créer une session de conversation avec `Conversation.startSession` : ```js const conversation = await Conversation.startSession(options); ``` Cette opération établit une connexion et utilise le microphone pour communiquer avec l’agent ElevenLabs Agents. Pensez à expliquer l’accès au microphone et à l’autoriser dans l’interface de votre application avant de démarrer la conversation : ```js // call after explaining to the user why the microphone access is needed await navigator.mediaDevices.getUserMedia({ audio: true }); ``` #### Configuration de la session Les options transmises à `startSession` définissent la manière dont la session est établie. Les conversations peuvent être démarrées avec des agents publics ou privés. ##### Agents publics Les agents ne nécessitant aucune authentification peuvent démarrer une conversation à l’aide de l’ID de l’agent. Vous pouvez obtenir cet ID dans l’[interface ElevenLabs](https://elevenlabs.io/app/conversational-ai). Pour les agents publics, vous pouvez utiliser l’ID directement : ```js const conversation = await Conversation.startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6", }); ``` > **Note** > > Le type de connexion est déduit automatiquement selon le mode de conversation. Les conversations vocales > utilisent WebRTC et les conversations uniquement textuelles utilisent WebSocket par défaut. Vous pouvez néanmoins spécifier explicitement > `connectionType: 'webrtc'` ou `connectionType: 'websocket'` si nécessaire. ##### Agents privés Si la conversation nécessite une autorisation, vous devez ajouter à votre serveur un endpoint dédié qui demandera soit une URL signée (en cas d’utilisation du type de connexion WebSockets), soit un jeton de conversation (en cas d’utilisation de WebRTC) via l’[API ElevenLabs](https://elevenlabs.io/docs/overview/intro), puis le transmettra au client. Voici un exemple pour une connexion WebSocket : ```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, }); ``` Voici un exemple pour 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); }); ``` Une fois le jeton obtenu, le transmettre à `startSession` lancera la conversation via WebRTC. ```js // Client const response = await fetch("/conversation-token", yourAuthHeaders); const conversationToken = await response.text(); const conversation = await Conversation.startSession({ conversationToken, }); ``` #### Callbacks facultatifs Les options transmises à `startSession` peuvent également servir à enregistrer des callbacks facultatifs : * **onConnect** : gestionnaire appelé lorsque la connexion WebSocket de la conversation est établie. * **onDisconnect** : gestionnaire appelé lorsque la connexion WebSocket de la conversation est terminée. * **onMessage** : gestionnaire appelé lorsqu’un nouveau message texte est reçu. Il peut s’agir de transcriptions provisoires ou finales de la voix de l’utilisateur, ou de réponses produites par un LLM. Principalement utilisé pour gérer la transcription de la conversation. * **onError** : gestionnaire appelé lorsqu’une erreur se produit. * **onStatusChange** : gestionnaire appelé à chaque changement d’état de la connexion. Peut être `connected`, `connecting` ou `disconnected` (initial). * **onModeChange** : gestionnaire appelé lorsqu’un état change, par exemple lorsque l’agent passe de `speaking` à `listening`, ou inversement. * **onCanSendFeedbackChange** : gestionnaire appelé lorsque l’envoi de commentaires devient disponible ou indisponible. * **onAudioAlignment** : gestionnaire appelé lorsque des données d’alignement audio sont reçues, fournissant des informations de timing au niveau des caractères pour la parole de l’agent. > **Warning** > > Tous les événements client ne sont pas activés par défaut pour un agent. Si vous avez activé un callback mais > ne recevez aucun événement, assurez-vous que l’événement correspondant est > activé pour votre agent ElevenLabs. Vous pouvez le faire dans l’onglet « Advanced » des paramètres de l’agent dans le Dashboard ElevenLabs. #### Valeur de retour `startSession` renvoie une instance de conversation (`VoiceConversation` ou `TextConversation` selon le mode) qui permet de contrôler la session. La méthode génère une erreur si la session ne peut pas être établie. Cela peut se produire si l’utilisateur refuse l’accès au microphone ou si la connexion échoue. **endSession** Méthode permettant de terminer manuellement la conversation. Elle termine la conversation et se déconnecte du WebSocket. L’instance de conversation devient ensuite inutilisable et peut être supprimée en toute sécurité. ```js await conversation.endSession(); ``` **getId** Méthode qui renvoie l’ID de la conversation. ```js const id = conversation.getId(); ``` **setVolume** Méthode permettant de définir le volume de sortie de la conversation. Accepte un objet dont le champ de volume est compris entre 0 et 1. ```js await conversation.setVolume({ volume: 0.5 }); ``` **getInputVolume / getOutputVolume** Méthodes qui renvoient le volume actuel d’entrée ou de sortie sur une échelle de `0` à `1`, où `0` correspond à -100 dB et `1` à -30 dB. ```js const inputVolume = await conversation.getInputVolume(); const outputVolume = await conversation.getOutputVolume(); ``` **sendFeedback** Méthode permettant d’envoyer un commentaire binaire à l’agent. Elle accepte une valeur booléenne, où `true` représente un commentaire positif et `false` un commentaire négatif. Les commentaires sont toujours associés à la réponse la plus récente de l’agent et ne peuvent être envoyés qu’une fois par réponse. Vous pouvez écouter `onCanSendFeedbackChange` pour savoir si un commentaire peut être envoyé à un instant donné. ```js conversation.sendFeedback(true); // positive feedback conversation.sendFeedback(false); // negative feedback ``` **sendContextualUpdate** Méthode permettant d’envoyer des mises à jour contextuelles à l’agent. Elle peut servir à informer l’agent d’actions de l’utilisateur qui ne sont pas directement liées à la conversation, mais peuvent influencer ses réponses. ```js conversation.sendContextualUpdate( "User navigated to another page. Consider it for next response, but don't react to this contextual update." ); ``` **sendUserMessage** Envoie un message texte à l’agent. Peut être utilisé pour permettre à l’utilisateur de saisir son message au lieu d’utiliser le microphone. Contrairement à `sendContextualUpdate`, ce message sera traité comme un message utilisateur et invitera l’agent à prendre son tour dans la conversation. ```js sendButton.addEventListener("click", (e) => { conversation.sendUserMessage(textInput.value); textInput.value = ""; }); ``` **sendUserActivity** Informe l’agent de l’activité de l’utilisateur. L’agent ne tentera pas de parler pendant au moins 2 secondes après la détection de l’activité de l’utilisateur. Cette méthode peut empêcher l’agent d’interrompre l’utilisateur lorsqu’il écrit. ```js textInput.addEventListener("input", () => { conversation.sendUserActivity(); }); ``` **setMicMuted** Méthode permettant d’activer ou de désactiver le son du microphone. ```js // Mute the microphone conversation.setMicMuted(true); // Unmute the microphone conversation.setMicMuted(false); ``` **changeInputDevice** Vous permet de changer de périphérique d’entrée audio pendant une conversation vocale active. Cette méthode est disponible uniquement pour les conversations vocales. > **Note** > > En mode WebRTC, le format d’entrée et la fréquence d’échantillonnage sont codés en dur sur `pcm` et `48000` respectivement. > Modifier ces valeurs lors du changement de périphérique d’entrée n’a aucun effet. ```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", }); ``` Si l’ID du périphérique n’est pas valide, le périphérique par défaut sera utilisé à la place. **changeOutputDevice** Vous permet de changer de périphérique de sortie audio pendant une conversation vocale active. Cette méthode est disponible uniquement pour les conversations vocales. > **Note** > > En mode WebRTC, le format de sortie et la fréquence d’échantillonnage sont codés en dur sur `pcm` et `48000` respectivement. > Modifier ces valeurs lors du changement de périphérique de sortie n’a aucun effet. ```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** > > Le changement de périphérique fonctionne uniquement pour les conversations vocales. Si aucun `deviceId` spécifique n’est fourni, > le navigateur utilisera sa sélection de périphérique par défaut. Vous pouvez répertorier les périphériques disponibles à l’aide de l’API > [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices). **getInputByteFrequencyData / getOutputByteFrequencyData** Méthodes qui renvoient des `Uint8Array` contenant les données de fréquence actuelles d’entrée ou de sortie. Consultez [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) pour plus d’informations. > **Note** > > Ces méthodes sont disponibles uniquement pour les conversations vocales. En mode WebRTC, l’audio est codé en dur pour > utiliser `pcm_48000`, ce qui signifie que toute visualisation utilisant les données renvoyées peut afficher des motifs différents > de ceux des connexions WebSocket.