SDK React

Installazione

Installa il pacchetto nel tuo progetto tramite il package manager.

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

Utilizzo

Ecco un esempio minimo funzionante che si connette a un agente e consente all’utente di avviare e terminare una conversazione 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>
  );
}

Le sezioni seguenti spiegano ogni parte nel dettaglio.

ConversationProvider

Tutti gli hook della conversazione devono essere usati all’interno di un ConversationProvider. Avvolgi la tua app (o il sottoalbero pertinente) con questo provider.

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

Proprietà del provider

Il provider accetta le stesse opzioni di useConversation, inclusi callback, strumenti client, override e posizione del server, così puoi configurarli a livello di provider anziché in ogni consumer dell’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>

Stato di disattivazione audio controllato

Il provider supporta le proprietà isMuted e onMutedChange per la gestione controllata dello stato di disattivazione audio, consentendoti di renderlo persistente esternamente, ad esempio tra le sessioni.

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

useConversation

Un pratico hook React che combina tutti gli hook granulari in un singolo valore restituito. Richiede un ConversationProvider antenato.

Inizializzare una conversazione

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

Tieni presente che ElevenAgents richiede l’accesso al microfono per le conversazioni vocali. Valuta di spiegare il motivo e consentire l’accesso nell’interfaccia della tua app prima dell’avvio della conversazione.

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

Opzioni

L’hook può essere inizializzato facoltativamente con delle opzioni. Puoi passarle anche a livello di ConversationProvider.

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

Le opzioni includono:

• clientTools - definizione dell’oggetto per gli strumenti client che possono essere richiamati dall’agente. Per i dettagli, vedi sotto.
• overrides - definizione dell’oggetto per gli override delle impostazioni della conversazione. Per i dettagli, vedi sotto.
• textOnly - indica se la conversazione deve essere eseguita in modalità solo testo. Per i dettagli, vedi sotto.
• serverLocation - specifica la posizione del server ("us", "eu-residency", "in-residency", "global"). Il valore predefinito è "us".

Panoramica dei callback

• onConnect - gestore chiamato quando viene stabilita la connessione della conversazione.
• onDisconnect - gestore chiamato quando la connessione della conversazione termina.
• onMessage - gestore chiamato quando viene ricevuto un nuovo messaggio. Può trattarsi di trascrizioni provvisorie o finali della voce dell’utente, risposte prodotte da LLM o messaggi di debug quando è abilitata un’opzione di debug.
• onError - gestore chiamato quando si verifica un errore.
• onAudio - gestore chiamato quando vengono ricevuti dati audio.
• onModeChange - gestore chiamato quando cambia la modalità della conversazione (conversazione/ascolto).
• onStatusChange - gestore chiamato quando cambia lo stato della connessione.
• onCanSendFeedbackChange - gestore chiamato quando cambia la possibilità di inviare feedback.
• onDebug - gestore chiamato quando sono disponibili informazioni di debug.
• onUnhandledClientToolCall - gestore chiamato quando viene rilevata una chiamata a uno strumento client non gestita.
• onVadScore - gestore chiamato quando cambia il punteggio del rilevamento dell’attività vocale.
• onAudioAlignment - gestore chiamato quando vengono ricevuti dati di allineamento audio, che forniscono informazioni sui tempi a livello di carattere per il parlato dell’agente.
• onAgentChatResponsePart - gestore chiamato con il testo della risposta dell’agente durante la generazione, come eventi di avvio, delta e arresto. Viene sempre inviato in modalità solo testo; per le conversazioni vocali, abilita agent_chat_response_part nella configurazione client_events dell’agente.

Strumenti client

Gli strumenti client consentono all’agente di richiamare funzionalità lato client. Puoi usarli per attivare azioni nel client, come aprire una finestra modale o effettuare una chiamata API per conto dell’utente.

La definizione degli strumenti client è un oggetto di funzioni e deve essere identica alla configurazione nella UI di ElevenLabs, dove puoi assegnare nome e descrizione ai diversi strumenti, oltre a configurare i parametri passati dall’agente.

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

Se la funzione restituisce un valore, questo viene passato all’agente come risposta.

Perché l’agente attenda la risposta e reagisca a essa, lo strumento deve essere impostato esplicitamente per bloccare la conversazione nella UI di ElevenLabs. In caso contrario, l’agente presume che l’operazione sia riuscita e prosegue la conversazione.

Override della conversazione

Puoi scegliere di sovrascrivere varie impostazioni della conversazione e impostarle dinamicamente in base ad altre interazioni dell’utente.

Supportiamo l’override di varie impostazioni. Sono facoltative e puoi usarle per personalizzare l’esperienza di conversazione.

Sono disponibili le seguenti impostazioni:

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

Solo testo

Se il tuo agente è configurato per essere eseguito in modalità solo testo, ovvero non invia né riceve messaggi audio, puoi usare questo flag per usare una versione più leggera della conversazione. In questo caso non verranno richiesti i permessi per il microfono e non verrà creato alcun contesto audio.

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

Stato controllato

Puoi controllare direttamente alcuni aspetti dello stato della conversazione tramite le opzioni dell’hook:

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

Residenza dei dati

Puoi specificare a quale regione del server ElevenLabs connetterti. Per maggiori informazioni, consulta la guida alla residenza dei dati.

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

Metodi

startSession

Il metodo startSession stabilisce la connessione e avvia l’uso del microfono per comunicare con l’agente ElevenLabs Agents. Il metodo accetta un oggetto di opzioni, per cui è obbligatorio signedUrl, conversationToken o agentId.

Puoi ottenere l’ID dell’agente dalla UI di ElevenLabs.

Ti consigliamo inoltre di passare i tuoi ID utente finali per associare le conversazioni ai tuoi utenti.

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

Per gli agenti pubblici, ovvero gli agenti senza autenticazione abilitata, è richiesto solo agentId.

Se la conversazione richiede autorizzazione, usa l’API REST per generare link firmati per una connessione WebSocket o un token di conversazione per una connessione WebRTC.

startSession restituisce una promise che risolve un conversationId. Il valore è un ID di conversazione univoco a livello globale che puoi usare per identificare conversazioni separate.

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

Un metodo per terminare manualmente la conversazione. Disconnette e termina la conversazione.

await conversation.endSession();

setVolume

Imposta il volume di output della conversazione. Accetta un oggetto con un campo volume compreso tra 0 e 1.

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

sendUserMessage

Invia un messaggio di testo all’agente.

Puoi usarlo per consentire all’utente di digitare il messaggio anziché usare il microfono. A differenza di sendContextualUpdate, verrà trattato come un messaggio utente e inviterà l’agente a intervenire nella conversazione.

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

Invia all’agente informazioni contestuali che non attiveranno una risposta.

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

sendFeedback

Fornisci feedback sulla qualità della conversazione. Questo aiuta a migliorare le prestazioni dell’agente.

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

sendUserActivity

Notifica all’agente l’attività dell’utente per evitare interruzioni. È utile quando l’utente sta usando attivamente l’app e l’agente dovrebbe interrompere il parlato, ad esempio quando l’utente sta digitando in una chat.

L’agente interromperà il parlato per circa 2 secondi dopo aver ricevuto questo segnale.

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

changeInputDevice

Cambia il dispositivo di input audio durante una conversazione vocale attiva. Questo metodo è disponibile solo per le conversazioni vocali.

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

changeOutputDevice

Cambia il dispositivo di output audio durante una conversazione vocale attiva. Questo metodo è disponibile solo per le conversazioni vocali.

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

getId

Restituisce l’ID della conversazione corrente.

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

getInputVolume / getOutputVolume

Metodi che restituiscono i livelli attuali del volume di input/output (scala 0-1).

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

getInputByteFrequencyData / getOutputByteFrequencyData

Metodi che restituiscono Uint8Array contenenti i dati di frequenza correnti di input/output. Per maggiori informazioni, consulta AnalyserNode.getByteFrequencyData.

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

sendMCPToolApprovalResult

Invia il risultato dell’approvazione per le chiamate di strumenti MCP (Model Context Protocol).

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

Valori restituiti

Oltre ai metodi sopra indicati, useConversation restituisce il seguente stato reattivo:

• status - lo stato corrente della connessione ("disconnected", "connecting", "connected").
• isSpeaking - indica se l’agente sta parlando.
• isListening - indica se l’agente sta ascoltando.
• mode - la modalità corrente della conversazione ("speaking" o "listening").
• isMuted - indica se il microfono è disattivato.
• setMuted - funzione per disattivare/riattivare il microfono.
• canSendFeedback - indica se è possibile inviare feedback per la conversazione corrente.
• message - l’ultimo messaggio della conversazione.

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>
);

Hook granulari

Per prestazioni di rendering migliori, usa questi hook anziché useConversation. Ogni hook si sottoscrive solo alla propria specifica porzione di stato, quindi i componenti eseguono un nuovo rendering solo quando cambiano i dati che utilizzano.

Tutti gli hook granulari richiedono un ConversationProvider antenato.

useConversationControls

Restituisce i metodi di azione per controllare la conversazione. Questo hook non provoca nuovi rendering poiché fornisce solo riferimenti a funzioni stabili.

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

Restituisce lo stato corrente della connessione e un messaggio di stato facoltativo.

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

useConversationInput

Restituisce lo stato di disattivazione dell’audio e un setter per attivare o disattivare il microfono.

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

useConversationMode

Restituisce lo stato di conversazione/ascolto dell’agente.

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

useConversationFeedback

Restituisce la disponibilità dei feedback e un metodo per inviarli.

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

Restituisce l’istanza della conversazione non elaborata. È una soluzione di emergenza per casi d’uso avanzati in cui ti serve l’accesso diretto all’oggetto VoiceConversation o TextConversation sottostante.

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

useConversationClientTool

Un hook per registrare dinamicamente strumenti client dai componenti React. Gli strumenti vengono annullati automaticamente quando il componente viene smontato.

È utile quando il gestore di uno strumento richiede l’accesso allo stato o alle proprietà del componente che non sono disponibili a livello di provider.

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} />;
}

L’hook usa sempre il valore più recente della closure del gestore, quindi non devi preoccuparti di stati obsoleti.