> 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 JavaScript > **Info** > > Veja também a [visão geral do ElevenAgents](/docs/pt/eleven-agents/overview) ## Instalação Instale o pacote no seu projeto usando um gerenciador de pacotes. ```shell npm install @elevenlabs/client # or yarn add @elevenlabs/client # or pnpm install @elevenlabs/client ``` > **Tip** > > Está atualizando 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 de importação e > atualizações da API. ## Uso Esta biblioteca é voltada principalmente ao desenvolvimento em projetos JavaScript puro ou como base para bibliotecas adaptadas a frameworks específicos. Recomendamos verificar se o seu framework específico tem uma biblioteca própria. No entanto, você pode usar esta biblioteca em qualquer projeto baseado em JavaScript. ### Inicializar conversa Primeiro, crie uma nova sessão de conversa usando `Conversation.startSession`: ```js const conversation = await Conversation.startSession(options); ``` Isso estabelecerá uma conexão e começará a usar o microfone para se comunicar com o agente do ElevenLabs Agents. Considere explicar e solicitar acesso ao microfone na interface do seu app antes de iniciar a conversa: ```js // call after explaining to the user why the microphone access is needed await navigator.mediaDevices.getUserMedia({ audio: true }); ``` #### Configuração da sessão As opções passadas para `startSession` especificam como a sessão é estabelecida. As conversas podem ser iniciadas com agentes públicos ou privados. ##### Agentes públicos Agentes que não exigem autenticação podem ser usados para iniciar uma conversa usando o ID do agente. O ID do agente pode ser obtido pela [interface da ElevenLabs](https://elevenlabs.io/app/conversational-ai). Para agentes públicos, você pode usar o ID diretamente: ```js const conversation = await Conversation.startSession({ agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6", }); ``` > **Note** > > O tipo de conexão é inferido automaticamente com base no modo de conversa. Conversas por voz > usam WebRTC, e conversas somente por texto usam WebSocket por padrão. Você ainda pode especificar explicitamente > `connectionType: 'webrtc'` ou `connectionType: 'websocket'`, se necessário. ##### Agentes privados Se a conversa exigir autorização, você precisará adicionar um endpoint dedicado ao seu servidor que solicite uma URL assinada (se usar o tipo de conexão WebSockets) ou um token de conversa (se usar WebRTC) usando a [API da ElevenLabs](https://elevenlabs.io/docs/overview/intro) e o envie de volta ao cliente. Veja um exemplo para uma 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}`, { 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); }); ``` ```js // Client const response = await fetch("/signed-url", yourAuthHeaders); const signedUrl = await response.text(); const conversation = await Conversation.startSession({ signedUrl, }); ``` Veja um exemplo para 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); }); ``` Depois que tiver o token, fornecê-lo a `startSession` iniciará a conversa usando WebRTC. ```js // Client const response = await fetch("/conversation-token", yourAuthHeaders); const conversationToken = await response.text(); const conversation = await Conversation.startSession({ conversationToken, }); ``` #### Callbacks opcionais As opções passadas para `startSession` também podem ser usadas para registrar callbacks opcionais: * **onConnect** - manipulador chamado quando a conexão WebSocket da conversa é estabelecida. * **onDisconnect** - manipulador chamado quando a conexão WebSocket da conversa é encerrada. * **onMessage** - manipulador chamado quando uma nova mensagem de texto é recebida. Elas podem ser transcrições provisórias ou finais da voz do usuário, ou respostas produzidas pelo LLM. Usado principalmente para processar a transcrição da conversa. * **onError** - manipulador chamado quando ocorre um erro. * **onStatusChange** - manipulador chamado sempre que o status da conexão muda. Pode ser `connected`, `connecting` e `disconnected` (inicial). * **onModeChange** - manipulador chamado quando um status muda, por exemplo, o agente muda de `speaking` para `listening` ou vice-versa. * **onCanSendFeedbackChange** - manipulador chamado quando o envio de feedback fica disponível ou indisponível. * **onAudioAlignment** - manipulador chamado quando dados de alinhamento de áudio são recebidos, fornecendo informações de tempo por caractere para a fala do agente. > **Warning** > > Nem todos os eventos do cliente são ativados por padrão para um agente. Se você ativou um callback, mas > não está recebendo eventos, verifique se o seu agente ElevenLabs tem o evento correspondente > ativado. Você pode fazer isso na aba "Advanced" das configurações do agente no painel da ElevenLabs. #### Valor de retorno `startSession` retorna uma instância de conversa (`VoiceConversation` ou `TextConversation`, dependendo do modo) que pode ser usada para controlar a sessão. O método gerará um erro se a sessão não puder ser estabelecida. Isso pode acontecer se o usuário negar o acesso ao microfone ou se a conexão falhar. **endSession** Um método para encerrar manualmente a conversa. O método encerrará a conversa e desconectará do WebSocket. Depois disso, a instância da conversa ficará inutilizável e poderá ser descartada com segurança. ```js await conversation.endSession(); ``` **getId** Um método que retorna o ID da conversa. ```js const id = conversation.getId(); ``` **setVolume** Um método para definir o volume de saída da conversa. Aceita um objeto com o campo de volume entre 0 e 1. ```js await conversation.setVolume({ volume: 0.5 }); ``` **getInputVolume / getOutputVolume** Métodos que retornam o volume atual de entrada/saída em uma escala de `0` a `1`, em que `0` é -100 dB e `1` é -30 dB. ```js const inputVolume = await conversation.getInputVolume(); const outputVolume = await conversation.getOutputVolume(); ``` **sendFeedback** Um método para enviar feedback binário ao agente. O método aceita um valor booleano, em que `true` representa feedback positivo e `false`, feedback negativo. O feedback é sempre associado à resposta mais recente do agente e só pode ser enviado uma vez por resposta. Você pode escutar `onCanSendFeedbackChange` para saber se é possível enviar feedback naquele momento. ```js conversation.sendFeedback(true); // positive feedback conversation.sendFeedback(false); // negative feedback ``` **sendContextualUpdate** Um método para enviar atualizações contextuais ao agente. Isso pode ser usado para informar o agente sobre ações do usuário que não estão diretamente relacionadas à conversa, mas podem influenciar as respostas do agente. ```js conversation.sendContextualUpdate( "User navigated to another page. Consider it for next response, but don't react to this contextual update." ); ``` **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. Diferentemente de `sendContextualUpdate`, isso será tratado como uma mensagem do usuário e fará com que o agente assuma seu turno na conversa. ```js sendButton.addEventListener("click", (e) => { conversation.sendUserMessage(textInput.value); textInput.value = ""; }); ``` **sendUserActivity** Notifica o agente sobre a atividade do usuário. O agente não tentará falar por pelo menos 2 segundos após detectar a atividade do usuário. Isso pode ser usado para evitar que o agente interrompa o usuário enquanto ele está digitando. ```js textInput.addEventListener("input", () => { conversation.sendUserActivity(); }); ``` **setMicMuted** Um método para silenciar/reativar o microfone. ```js // Mute the microphone conversation.setMicMuted(true); // Unmute the microphone conversation.setMicMuted(false); ``` **changeInputDevice** Permite alterar o dispositivo de entrada de áudio durante uma conversa por voz ativa. Este método está disponível apenas para conversas por voz. > **Note** > > No modo WebRTC, o formato de entrada e a taxa de amostragem são definidos como `pcm` e `48000`, respectivamente. > Alterar esses valores ao trocar o dispositivo de entrada não tem efeito. ```js 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", }); ``` Se o ID do dispositivo for inválido, o dispositivo padrão será usado. **changeOutputDevice** Permite alterar o dispositivo de saída de áudio durante uma conversa por voz ativa. Este método está disponível apenas para conversas por voz. > **Note** > > No modo WebRTC, o formato de saída e a taxa de amostragem são definidos como `pcm` e `48000`, respectivamente. > Alterar esses valores ao trocar o dispositivo de saída não tem efeito. ```js 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", }); ``` > **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). **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. > **Note** > > Esses métodos estão disponíveis apenas para conversas por voz. No modo WebRTC, o áudio é configurado para > usar `pcm_48000`, o que significa que qualquer visualização que use os dados retornados pode mostrar padrões diferentes > das conexões WebSocket.