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

> **Info**
>
> Consulte a [visão geral do ElevenAgents](/docs/pt/eleven-agents/overview) para entender como o
> ElevenAgents funciona.

## Instalação

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

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

> **Tip**
>
> Está migrando de uma versão anterior? Execute `npx skills add elevenlabs/packages` para instalar a
> habilidade `elevenlabs:sdk-migration` para seu agente de programação com IA, que automatiza alterações nas importações,
> o encapsulamento com `ConversationProvider` e atualizações da API.

> **Note**
>
> `@elevenlabs/react` reexporta tudo de `@elevenlabs/client`, então você não precisa instalar
> os dois pacotes.

## 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:

```tsx
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.

```tsx
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.

```tsx
<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).

```tsx
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.

> **Note**
>
> Para melhor desempenho de renderização, considere usar os [hooks granulares](#granular-hooks).
> `useConversation` aciona uma nova renderização em qualquer mudança de estado, enquanto os hooks granulares só
> renderizam novamente quando sua fatia específica do estado muda.

#### Inicializar conversa

```tsx
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.

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

```tsx
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](#client-tools) os detalhes.
* **overrides** - definição de objeto para substituições das configurações da conversa. Consulte [abaixo](#conversation-overrides) os detalhes.
* **textOnly** - se a conversa deve ser executada no modo somente texto. Consulte [abaixo](#text-only) 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](https://elevenlabs.io/app/agents), onde você pode nomear e descrever diferentes ferramentas, além de configurar os parâmetros passados pelo agente.

```ts
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.

> **Note**
>
> Para uma abordagem mais idiomática em React para registrar ferramentas do cliente, consulte
> [useConversationClientTool](#useconversationclienttool).

##### 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:

```ts
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.

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

##### Estado controlado

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

```ts
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](/docs/pt/overview/administration/data-residency).

```ts
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](https://elevenlabs.io/app/agents).

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

> **Note**
>
> O tipo de conexão é inferido automaticamente com base no modo da conversa. Conversas por voz
> usam WebRTC e conversas somente texto usam WebSocket por padrão. Você ainda pode especificar explicitamente
> `connectionType`, se necessário.

```js
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.

#### Conexão 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}`,
    {
      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);
});
```

```js
// Client

const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();

await conversation.startSession({
  signedUrl,
});
```

#### Conexão 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);
});
```

```js
// Client

const response = await fetch("/conversation-token", yourAuthHeaders);
const conversationToken = await response.text();

await conversation.startSession({
  conversationToken,
});
```

##### endSession

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

```js
await conversation.endSession();
```

##### setVolume

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

```js
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.

```js
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.

```js
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.

```js
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.

```js
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.

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

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

> **Note**
>
> A troca de dispositivo funciona apenas em conversas por voz. Se nenhum `deviceId` específico for fornecido, o
> navegador usará a seleção de dispositivo padrão. Você pode listar os dispositivos disponíveis usando a
> API [MediaDevices.enumerateDevices()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices).

##### getId

Retorna o ID da conversa atual.

```js
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).

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

##### getInputByteFrequencyData / getOutputByteFrequencyData

Métodos que retornam `Uint8Array`s contendo os dados atuais de frequência de entrada/saída. Consulte [AnalyserNode.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) para mais informações.

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

> **Note**
>
> Esses métodos estão disponíveis apenas para conversas por voz. No modo WebRTC, o áudio é codificado para
> usar `pcm_48000`, o que significa que qualquer visualização com os dados retornados pode mostrar padrões diferentes
> das conexões WebSocket.

##### sendMCPToolApprovalResult

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

```js
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.