SDK React

Installation

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

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

Utilisation

Voici un exemple minimal fonctionnel qui se connecte à un agent et permet à l’utilisateur de démarrer et de terminer une conversation vocale :

import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from "@elevenlabs/react";
function App() {
  return (
    <ConversationProvider>
      <Agent />
    </ConversationProvider>
  );
}
function Agent() {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();
  if (status === "connected") {
    return <button onClick={endSession}>End</button>;
  }
  return (
    <button onClick={() => startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6" })}>
      Start
    </button>
  );
}

Les sections ci-dessous expliquent chaque élément en détail.

ConversationProvider

Tous les hooks de conversation doivent être utilisés dans un ConversationProvider. Encapsulez votre application, ou le sous-arbre concerné, avec ce fournisseur.

import { ConversationProvider } from "@elevenlabs/react";
function App() {
  return (
    <ConversationProvider>
      <YourComponents />
    </ConversationProvider>
  );
}

Propriétés du fournisseur

Le fournisseur accepte les mêmes options que useConversation, notamment les callbacks, outils client, remplacements et l’emplacement du serveur. Vous pouvez ainsi les configurer au niveau du fournisseur plutôt que dans chaque consommateur de hook.

<ConversationProvider
  onConnect={() => console.log("Connected")}
  onDisconnect={() => console.log("Disconnected")}
  onError={(error) => console.error("Error:", error)}
  clientTools={{
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);
      return "Message displayed";
    },
  }}
  serverLocation="eu-residency"
>
  <YourComponents />
</ConversationProvider>

État de mise en sourdine contrôlé

Le fournisseur prend en charge les propriétés isMuted et onMutedChange pour gérer un état de mise en sourdine contrôlé, ce qui vous permet de conserver cet état en externe, par exemple entre les sessions.

const [muted, setMuted] = useState(false);
<ConversationProvider isMuted={muted} onMutedChange={setMuted}>
  <YourComponents />
</ConversationProvider>;

useConversation

Un hook React pratique qui combine tous les hooks granulaires dans une seule valeur de retour. Nécessite un ConversationProvider parent.

Initialiser une conversation

import { useConversation } from "@elevenlabs/react";
function MyComponent() {
  const conversation = useConversation();
  // ...
}

Notez qu’ElevenAgents nécessite l’accès au microphone pour les conversations vocales. Envisagez d’expliquer cet accès et de l’autoriser dans l’interface de votre application avant le début de la conversation.

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

Options

Le hook peut être initialisé avec des options. Vous pouvez également les transmettre au niveau de ConversationProvider.

const conversation = useConversation({
  /* options object */
});

Les options incluent :

• clientTools : définition d’objet pour les outils client pouvant être appelés par l’agent. Voir ci-dessous pour plus de détails.
• overrides : définition d’objet pour les remplacements des paramètres de conversation. Voir ci-dessous pour plus de détails.
• textOnly : indique si la conversation doit fonctionner en mode texte uniquement. Voir ci-dessous pour plus de détails.
• serverLocation : spécifie l’emplacement du serveur ("us", "eu-residency", "in-residency", "global"). La valeur par défaut est "us".

Présentation des callbacks

• onConnect : gestionnaire appelé lorsque la connexion de la conversation est établie.
• onDisconnect : gestionnaire appelé lorsque la connexion de la conversation est terminée.
• onMessage : gestionnaire appelé lorsqu’un nouveau message est reçu. Il peut s’agir de transcriptions provisoires ou finales de la voix de l’utilisateur, de réponses générées par un LLM ou d’un message de débogage lorsqu’une option de débogage est activée.
• onError : gestionnaire appelé lorsqu’une erreur se produit.
• onAudio : gestionnaire appelé lorsque des données audio sont reçues.
• onModeChange : gestionnaire appelé lorsque le mode de conversation change (parole/écoute).
• onStatusChange : gestionnaire appelé lorsque l’état de la connexion change.
• onCanSendFeedbackChange : gestionnaire appelé lorsque la possibilité d’envoyer des commentaires change.
• onDebug : gestionnaire appelé lorsque des informations de débogage sont disponibles.
• onUnhandledClientToolCall : gestionnaire appelé lorsqu’un appel d’outil client non géré est rencontré.
• onVadScore : gestionnaire appelé lorsque le score de détection d’activité vocale change.
• onAudioAlignment : gestionnaire appelé lorsque des données d’alignement audio sont reçues, fournissant des informations de synchronisation au niveau des caractères pour la parole de l’agent.
• onAgentChatResponsePart : gestionnaire appelé avec le texte de réponse de l’agent au fur et à mesure de sa génération, sous forme d’événements de début, delta et fin. Toujours envoyé en mode texte uniquement ; pour les conversations vocales, activez agent_chat_response_part dans la configuration client_events de l’agent.

Outils client

Les outils client permettent à l’agent d’appeler des fonctionnalités côté client. Ils peuvent déclencher des actions dans le client, comme ouvrir une fenêtre modale ou effectuer un appel API pour le compte de l’utilisateur.

La définition des outils client est un objet de fonctions. Elle doit être identique à votre configuration dans l’interface ElevenLabs, où vous pouvez nommer et décrire différents outils, ainsi que configurer les paramètres transmis par l’agent.

const conversation = useConversation({
  clientTools: {
    displayMessage: (parameters: { text: string }) => {
      alert(parameters.text);
      return "Message displayed";
    },
  },
});

Si la fonction renvoie une valeur, elle est transmise à l’agent en tant que réponse.

L’outil doit être explicitement configuré pour bloquer la conversation dans l’interface ElevenLabs afin que l’agent puisse attendre la réponse et y réagir. Sinon, l’agent suppose que l’opération a réussi et poursuit la conversation.

Remplacements de conversation

Vous pouvez remplacer différents paramètres de la conversation et les définir dynamiquement selon d’autres interactions utilisateur.

Nous prenons en charge le remplacement de plusieurs paramètres. Ces paramètres sont facultatifs et permettent de personnaliser l’expérience de conversation.

Les paramètres suivants sont disponibles :

const conversation = useConversation({
  overrides: {
    agent: {
      prompt: {
        prompt: "My custom prompt",
      },
      firstMessage: "My custom first message",
      language: "en",
    },
    tts: {
      voiceId: "custom voice id",
    },
    conversation: {
      textOnly: true,
    },
  },
});

Texte uniquement

Si votre agent est configuré pour fonctionner en mode texte uniquement, c’est-à-dire qu’il n’envoie ni ne reçoit de messages audio, vous pouvez utiliser cet indicateur pour employer une version plus légère de la conversation. Dans ce cas, l’utilisateur ne sera pas invité à autoriser le microphone et aucun contexte audio ne sera créé.

const conversation = useConversation({
  textOnly: true,
});

État contrôlé

Vous pouvez contrôler directement certains aspects de l’état de la conversation via les options du hook :

const [micMuted, setMicMuted] = useState(false);
const conversation = useConversation({
  micMuted,
  // ... other options
});
// Update controlled state
setMicMuted(true); // This will automatically mute the microphone

Résidence des données

Vous pouvez spécifier la région de serveur ElevenLabs à laquelle vous connecter. Pour en savoir plus, consultez le guide sur la résidence des données.

const conversation = useConversation({
  serverLocation: "eu-residency", // or "us", "in-residency", "global"
});

Méthodes

startSession

La méthode startSession établit la connexion et commence à utiliser le microphone pour communiquer avec l’agent ElevenLabs Agents. La méthode accepte un objet d’options, dans lequel signedUrl, conversationToken ou agentId est requis.

Vous pouvez obtenir l’ID de l’agent via l’interface ElevenLabs.

Nous vous recommandons également de transmettre vos propres ID d’utilisateurs finaux pour associer les conversations à vos utilisateurs.

const conversation = useConversation();
// For public agents, pass in the agent ID
const conversationId = await conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  userId: "user_9302xkm82nds93", // optional field
});

Pour les agents publics, c’est-à-dire les agents sans authentification activée, seul agentId est requis.

Si la conversation nécessite une autorisation, utilisez l’API REST pour générer des liens signés pour une connexion WebSocket ou un jeton de conversation pour une connexion WebRTC.

startSession renvoie une promesse résolue avec un conversationId. Cette valeur est un ID de conversation globalement unique que vous pouvez utiliser pour identifier des conversations distinctes.

// 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}`,
    {
      headers: {
        // Requesting a signed url 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 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();
await conversation.startSession({
  signedUrl,
});

endSession

Méthode permettant de terminer manuellement la conversation. Elle déconnecte et met fin à la conversation.

await conversation.endSession();

setVolume

Définit le volume de sortie de la conversation. Accepte un objet avec un champ volume compris entre 0 et 1.

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

sendUserMessage

Envoie un message texte à l’agent.

Peut être utilisé pour permettre à l’utilisateur de saisir le 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.

const { sendUserMessage, sendUserActivity } = useConversation();
const [value, setValue] = useState("");
return (
  <>
    <input
      value={value}
      onChange={e => {
        setValue(e.target.value);
        sendUserActivity();
      }}
    />
    <button
      onClick={() => {
        sendUserMessage(value);
        setValue("");
      }}
    >
      SEND
    </button>
  </>
);

sendContextualUpdate

Envoie à l’agent des informations contextuelles qui ne déclencheront pas de réponse.

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

sendFeedback

Fournit un retour sur la qualité de la conversation. Cela contribue à améliorer les performances de l’agent.

const { sendFeedback } = useConversation();
sendFeedback(true); // positive feedback
sendFeedback(false); // negative feedback

sendUserActivity

Informe l’agent de l’activité de l’utilisateur afin d’éviter les interruptions. Utile lorsque l’utilisateur utilise activement l’application et que l’agent doit interrompre sa parole, par exemple lorsque l’utilisateur écrit dans un chat.

L’agent interrompt sa parole pendant environ 2 secondes après réception de ce signal.

const { sendUserActivity } = useConversation();
// Call this when user is typing to prevent interruption
sendUserActivity();

changeInputDevice

Change le périphérique d’entrée audio pendant une conversation vocale active. Cette méthode est disponible uniquement pour les conversations vocales.

// Change to a specific input device
conversation.changeInputDevice({
  sampleRate: 16000,
  format: "pcm",
  preferHeadphonesForIosDevices: true,
  inputDeviceId: "a1b2c3d4e5f6", // Optional: specific device ID
});

changeOutputDevice

Change le périphérique de sortie audio pendant une conversation vocale active. Cette méthode est disponible uniquement pour les conversations vocales.

// Change to a specific output device
conversation.changeOutputDevice({
  sampleRate: 16000,
  format: "pcm",
  outputDeviceId: "a1b2c3d4e5f6", // Optional: specific device ID
});

getId

Renvoie l’ID de la conversation actuelle.

const { getId } = useConversation();
const conversationId = getId();
console.log(conversationId); // e.g., "conv_9001k1zph3fkeh5s8xg9z90swaqa"

getInputVolume / getOutputVolume

Méthodes qui renvoient les niveaux actuels de volume d’entrée/sortie, sur une échelle de 0 à 1.

const { getInputVolume, getOutputVolume } = useConversation();
const inputLevel = getInputVolume();
const outputLevel = getOutputVolume();

getInputByteFrequencyData / getOutputByteFrequencyData

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

const { getInputByteFrequencyData, getOutputByteFrequencyData } = useConversation();
const inputFrequencyData = getInputByteFrequencyData();
const outputFrequencyData = getOutputByteFrequencyData();

sendMCPToolApprovalResult

Envoie le résultat d’approbation pour les appels d’outils MCP (Model Context Protocol).

const { sendMCPToolApprovalResult } = useConversation();
// Approve a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", true);
// Reject a tool call
sendMCPToolApprovalResult("tc_8k2m4n6p8r0t", false);

Valeurs de retour

En plus des méthodes ci-dessus, useConversation renvoie l’état réactif suivant :

• status : l’état actuel de la connexion ("disconnected", "connecting", "connected").
• isSpeaking : indique si l’agent parle actuellement.
• isListening : indique si l’agent écoute actuellement.
• mode : le mode actuel de la conversation ("speaking" ou "listening").
• isMuted : indique si le microphone est actuellement en sourdine.
• setMuted : fonction permettant de couper/rétablir le son du microphone.
• canSendFeedback : indique si des commentaires peuvent être envoyés pour la conversation actuelle.
• message : le dernier message de la conversation.

const { status, isSpeaking, isListening, isMuted, setMuted, canSendFeedback } = useConversation();
return (
  <div>
    <p>Status: {status}</p>
    <p>Agent is {isSpeaking ? 'speaking' : 'listening'}</p>
    <button onClick={() => setMuted(!isMuted)}>
      {isMuted ? 'Unmute' : 'Mute'}
    </button>
  </div>
);

Hooks granulaires

Pour de meilleures performances de rendu, utilisez ces hooks plutôt que useConversation. Chaque hook s’abonne uniquement à sa partie spécifique de l’état, de sorte que les composants ne sont mis à jour que lorsque les données qu’ils utilisent changent.

Tous les hooks granulaires nécessitent un ConversationProvider parent.

useConversationControls

Renvoie les méthodes d’action permettant de contrôler la conversation. Ce hook ne provoque pas de nouveaux rendus, car il fournit uniquement des références de fonctions stables.

import { useConversationControls } from "@elevenlabs/react";
function Controls() {
  const {
    startSession,
    endSession,
    sendUserMessage,
    sendContextualUpdate,
    sendUserActivity,
    setVolume,
    changeInputDevice,
    changeOutputDevice,
    sendMCPToolApprovalResult,
    getId,
    getInputVolume,
    getOutputVolume,
    getInputByteFrequencyData,
    getOutputByteFrequencyData,
  } = useConversationControls();
  return (
    <button onClick={() => startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6" })}>
      Start
    </button>
  );
}

useConversationStatus

Renvoie l’état actuel de la connexion et un message d’état facultatif.

import { useConversationStatus } from "@elevenlabs/react";
function StatusIndicator() {
  const { status, message } = useConversationStatus();
  return <p>Status: {status}</p>; // "disconnected" | "connecting" | "connected"
}

useConversationInput

Renvoie l’état de mise en sourdine et une fonction de définition pour activer ou désactiver le microphone.

import { useConversationInput } from "@elevenlabs/react";
function MuteToggle() {
  const { isMuted, setMuted } = useConversationInput();
  return <button onClick={() => setMuted(!isMuted)}>{isMuted ? "Unmute" : "Mute"}</button>;
}

useConversationMode

Renvoie l’état de parole/d’écoute de l’agent.

import { useConversationMode } from "@elevenlabs/react";
function ModeIndicator() {
  const { mode, isSpeaking, isListening } = useConversationMode();
  return <p>Agent is {isSpeaking ? "speaking" : "listening"}</p>;
}

useConversationFeedback

Renvoie la disponibilité des commentaires et une méthode pour les envoyer.

import { useConversationFeedback } from "@elevenlabs/react";
function FeedbackButtons() {
  const { canSendFeedback, sendFeedback } = useConversationFeedback();
  if (!canSendFeedback) return null;
  return (
    <div>
      <button onClick={() => sendFeedback(true)}>Like</button>
      <button onClick={() => sendFeedback(false)}>Dislike</button>
    </div>
  );
}

useRawConversation

Renvoie l’instance brute de conversation. Il s’agit d’une solution de contournement pour les cas d’usage avancés où vous avez besoin d’un accès direct à l’objet VoiceConversation ou TextConversation sous-jacent.

import { useRawConversation } from "@elevenlabs/react";
function Advanced() {
  const conversation = useRawConversation();
  // Access the raw conversation instance directly
}

useConversationClientTool

Un hook pour enregistrer dynamiquement des outils client depuis des composants React. Les outils sont automatiquement désenregistrés lorsque le composant est démonté.

Cela est utile lorsque le gestionnaire d’un outil a besoin d’accéder à l’état ou aux propriétés du composant, qui ne sont pas disponibles au niveau du fournisseur.

import { useConversationClientTool } from "@elevenlabs/react";
import { useState } from "react";
function MapComponent() {
  const [location, setLocation] = useState({ lat: 0, lng: 0 });
  useConversationClientTool("getLocation", () => {
    return `${location.lat},${location.lng}`;
  });
  useConversationClientTool("setLocation", (params: { lat: number; lng: number }) => {
    setLocation(params);
    return "Location updated";
  });
  return <Map center={location} />;
}

Le hook utilise toujours la dernière valeur de fermeture du gestionnaire, vous n’avez donc pas à vous soucier d’un état obsolète.