SDK JavaScript

Installation

Installez le package dans votre projet via votre gestionnaire de packages.

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

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 :

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 :

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

Pour les agents publics, vous pouvez utiliser l’ID directement :

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

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, puis le transmettra au client.

Voici un exemple pour une connexion 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,
});

Voici un exemple pour 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);
});

Une fois le jeton obtenu, le transmettre à startSession lancera la conversation via WebRTC.

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

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

await conversation.endSession();

getId

Méthode qui renvoie l’ID de la conversation.

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.

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.

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

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.

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.

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.

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

setMicMuted

Méthode permettant d’activer ou de désactiver le son du microphone.

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

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.

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

Méthodes qui renvoient des Uint8Array contenant les données de fréquence actuelles d’entrée ou de sortie. Consultez AnalyserNode.getByteFrequencyData pour plus d’informations.