SDK React

Instalação

Instale o pacote no seu projeto usando um gerenciador de pacotes.

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

Uso

Aqui está um exemplo mínimo funcional que se conecta a um agente e permite que o usuário inicie e encerre uma conversa por voz:

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

As seções abaixo explicam cada parte em detalhes.

ConversationProvider

Todos os hooks de conversa devem ser usados em um ConversationProvider. Envolva seu app (ou a subárvore relevante) com esse provider.

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

Props do provider

O provider aceita as mesmas opções de useConversation — incluindo callbacks, ferramentas do cliente, substituições e localização do servidor — para que você possa configurá-las no nível do provider, em vez de em cada consumidor 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>

Estado de silenciamento controlado

O provider é compatível com as props isMuted e onMutedChange para gerenciamento controlado do estado de silenciamento, permitindo que você mantenha o estado de silenciamento externamente (por exemplo, entre sessões).

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

useConversation

Um hook React prático que combina todos os hooks granulares em um único valor de retorno. Requer um ConversationProvider ancestral.

Inicializar conversa

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

Observe que o ElevenAgents requer acesso ao microfone para conversas por voz. Considere explicar isso e permitir o acesso na interface do seu app antes do início da conversa.

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

Opções

O hook pode ser inicializado opcionalmente com opções. Elas também podem ser passadas no nível de ConversationProvider.

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

As opções incluem:

• clientTools - definição de objeto para ferramentas do cliente que podem ser chamadas pelo agente. Consulte abaixo os detalhes.
• overrides - definição de objeto para substituições das configurações da conversa. Consulte abaixo os detalhes.
• textOnly - se a conversa deve ser executada no modo somente texto. Consulte abaixo os detalhes.
• serverLocation - especifica a localização do servidor ("us", "eu-residency", "in-residency", "global"). O padrão é "us".

Visão geral dos callbacks

• onConnect - manipulador chamado quando a conexão da conversa é estabelecida.
• onDisconnect - manipulador chamado quando a conexão da conversa é encerrada.
• onMessage - manipulador chamado quando uma nova mensagem é recebida. Podem ser transcrições provisórias ou finais da voz do usuário, respostas produzidas pelo LLM ou mensagens de depuração quando uma opção de depuração está ativada.
• onError - manipulador chamado quando um erro é encontrado.
• onAudio - manipulador chamado quando dados de áudio são recebidos.
• onModeChange - manipulador chamado quando o modo da conversa muda (falando/ouvindo).
• onStatusChange - manipulador chamado quando o status da conexão muda.
• onCanSendFeedbackChange - manipulador chamado quando a possibilidade de enviar feedback muda.
• onDebug - manipulador chamado quando informações de depuração estão disponíveis.
• onUnhandledClientToolCall - manipulador chamado quando uma chamada não tratada de ferramenta do cliente é encontrada.
• onVadScore - manipulador chamado quando a pontuação da detecção de atividade de voz muda.
• onAudioAlignment - manipulador chamado quando dados de alinhamento de áudio são recebidos, fornecendo informações de tempo no nível de caracteres para a fala do agente.
• onAgentChatResponsePart - manipulador chamado com o texto da resposta do agente à medida que ele é gerado, como eventos de início, delta e parada. Sempre enviado no modo somente texto; para conversas por voz, ative agent_chat_response_part na configuração client_events do agente.

Ferramentas do cliente

As ferramentas do cliente permitem que o agente chame funcionalidades do lado do cliente. Elas podem ser usadas para acionar ações no cliente, como abrir um modal ou fazer uma chamada de API em nome do usuário.

A definição das ferramentas do cliente é um objeto de funções e precisa ser idêntica à sua configuração na interface da ElevenLabs, onde você pode nomear e descrever diferentes ferramentas, além de configurar os parâmetros passados pelo agente.

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

Se a função retornar um valor, ele será enviado de volta ao agente como resposta.

A ferramenta precisa estar explicitamente configurada para bloquear a conversa na interface da ElevenLabs para que o agente aguarde e reaja à resposta. Caso contrário, o agente presume que houve sucesso e continua a conversa.

Substituições da conversa

Você pode substituir várias configurações da conversa e defini-las dinamicamente com base em outras interações do usuário.

Oferecemos suporte à substituição de várias configurações. Essas configurações são opcionais e podem ser usadas para personalizar a experiência de conversa.

As seguintes configurações estão disponíveis:

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

Somente texto

Se seu agente estiver configurado para ser executado no modo somente texto, ou seja, não enviar nem receber mensagens de áudio, você poderá usar essa flag para usar uma versão mais leve da conversa. Nesse caso, o usuário não precisará conceder permissões de microfone e nenhum contexto de áudio será criado.

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

Estado controlado

Você pode controlar determinados aspectos do estado da conversa diretamente pelas opções do hook:

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

Residência de dados

Você pode especificar a qual região de servidor da ElevenLabs se conectar. Para mais informações, consulte o guia de residência de dados.

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

Métodos

startSession

O método startSession estabelece a conexão e começa a usar o microfone para se comunicar com o agente do ElevenLabs Agents. O método aceita um objeto de opções, sendo obrigatório informar signedUrl, conversationToken ou agentId.

O ID do agente pode ser obtido pela interface da ElevenLabs.

Também recomendamos informar seus próprios IDs de usuário final para associar conversas aos seus usuários.

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

Para agentes públicos (ou seja, agentes sem autenticação ativada), somente o agentId é necessário.

Se a conversa exigir autorização, use a API REST para gerar links assinados para uma conexão WebSocket ou um token de conversa para uma conexão WebRTC.

startSession retorna uma promise que é resolvida como um conversationId. O valor é um ID de conversa globalmente único que você pode usar para identificar conversas separadas.

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

Um método para encerrar manualmente a conversa. Ele desconectará e encerrará a conversa.

await conversation.endSession();

setVolume

Define o volume de saída da conversa. Aceita um objeto com um campo volume entre 0 e 1.

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

sendUserMessage

Envia uma mensagem de texto ao agente.

Pode ser usado para permitir que o usuário digite a mensagem em vez de usar o microfone. Ao contrário de sendContextualUpdate, isso será tratado como uma mensagem do usuário e fará com que o agente tome seu turno na conversa.

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

Envia informações contextuais ao agente sem acionar uma resposta.

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

sendFeedback

Fornece feedback sobre a qualidade da conversa. Isso ajuda a melhorar o desempenho do agente.

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

sendUserActivity

Notifica o agente sobre a atividade do usuário para evitar interrupções. Útil quando o usuário está usando ativamente o app e o agente deve pausar a fala, por exemplo, quando o usuário está digitando em um chat.

O agente pausará a fala por cerca de 2 segundos após receber esse sinal.

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

changeInputDevice

Troca o dispositivo de entrada de áudio durante uma conversa por voz ativa. Esse método está disponível apenas para conversas por voz.

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

changeOutputDevice

Troca o dispositivo de saída de áudio durante uma conversa por voz ativa. Esse método está disponível apenas para conversas por voz.

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

getId

Retorna o ID da conversa atual.

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

getInputVolume / getOutputVolume

Métodos que retornam os níveis atuais de volume de entrada/saída (escala de 0 a 1).

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

getInputByteFrequencyData / getOutputByteFrequencyData

Métodos que retornam Uint8Arrays contendo os dados atuais de frequência de entrada/saída. Consulte AnalyserNode.getByteFrequencyData para mais informações.

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

sendMCPToolApprovalResult

Envia o resultado de aprovação para chamadas de ferramentas MCP (Model Context Protocol).

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

Valores de retorno

Além dos métodos acima, useConversation retorna o seguinte estado reativo:

• status - o status atual da conexão ("disconnected", "connecting", "connected").
• isSpeaking - se o agente está falando no momento.
• isListening - se o agente está ouvindo no momento.
• mode - o modo atual da conversa ("speaking" ou "listening").
• isMuted - se o microfone está silenciado no momento.
• setMuted - função para silenciar/reativar o microfone.
• canSendFeedback - se é possível enviar feedback para a conversa atual.
• message - a mensagem mais recente da conversa.

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 granulares

Para melhor desempenho de renderização, use estes hooks em vez de useConversation. Cada hook assina apenas sua fatia específica do estado, portanto os componentes só são renderizados novamente quando os dados que consomem mudam.

Todos os hooks granulares exigem um ConversationProvider ancestral.

useConversationControls

Retorna métodos de ação para controlar a conversa. Esse hook não causa novas renderizações, pois fornece apenas referências estáveis de funções.

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

Retorna o status atual da conexão e uma mensagem de status opcional.

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

useConversationInput

Retorna o estado de silenciamento e uma função setter para alternar o microfone.

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

useConversationMode

Retorna o estado de fala/escuta do agente.

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

useConversationFeedback

Retorna a disponibilidade de feedback e um método para enviá-lo.

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

Retorna a instância bruta da conversa. Esta é uma alternativa para casos de uso avançados em que você precisa de acesso direto ao objeto VoiceConversation ou TextConversation subjacente.

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

useConversationClientTool

Um hook para registrar dinamicamente ferramentas de cliente a partir de componentes React. As ferramentas são removidas automaticamente quando o componente é desmontado.

Isso é útil quando o manipulador de uma ferramenta precisa acessar o estado ou as props do componente que não estão disponíveis no nível do provedor.

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

O hook sempre usa o valor mais recente do closure do manipulador, então você não precisa se preocupar com estado desatualizado.