SDK JavaScript

Instalação

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

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

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:

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:

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

Para agentes públicos, você pode usar o ID diretamente:

const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});

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 e o envie de volta ao cliente.

Veja um exemplo para uma conexão WebSocket:

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

// Client
const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();
const conversation = await Conversation.startSession({
  signedUrl,
});

Veja um exemplo para WebRTC:

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

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

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.

await conversation.endSession();

getId

Um método que retorna o ID da conversa.

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.

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.

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.

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.

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.

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.

textInput.addEventListener("input", () => {
  conversation.sendUserActivity();
});

setMicMuted

Um método para silenciar/reativar o microfone.

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

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.

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

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.